SDK
Einen Batch senden
`emails.sendBatch`: bis zu 100 Nachrichten, Ergebnisse pro Eintrag.
emails.sendBatch
const result = await openemail.emails.sendBatch(invoices.map(toMessage)) console.log(result.sent, 'sent,', result.failed, 'failed') for (const item of result.items) { if (item.status === 'error') console.error(item.index, item.error.code, item.error.message) else console.log(item.index, item.email.id)}items enthält einen Eintrag pro Eingabe, in derselben Reihenfolge, jeweils entweder ok mit der Nachricht oder error mit dem Fehlerumschlag, mit dem diese Nachricht abgelehnt worden wäre. Nichts wird zurückgerollt, failed > 0 ist daher eine Liste zum Abarbeiten und kein Grund, den Batch erneut zu senden.
Ein Idempotency-Key deckt den gesamten Batch ab und der Server erweitert ihn pro Eintrag, ein wiederholter Batch spielt daher jede Nachricht erneut ab, statt sie alle auf die erste zusammenfallen zu lassen.
Parameter: emails.sendBatch
emailsEmailSend[]erforderlich- Eine bis 100 Nachrichten, serialisiert als `{ "emails": [...] }` und einzeln in der angegebenen Reihenfolge angenommen. Ein leeres array, mehr als 100 Einträge oder mehr als 10 Einträge mit `translate` lassen den gesamten Aufruf mit einem `validation_error` auf `emails` scheitern. Ebenso ein fehlender Scope `emails:send`, ein Body, der weder ein array noch `{ emails: [...] }` ist, und ein fehlerhafter `Idempotency-Key`, all dies, bevor eine einzige Nachricht gesendet wird.
options.idempotencyKeystring- Dedupliziert den Batch prozessübergreifend. Der Client hängt ohnehin bei jedem Aufruf einen frisch erzeugten Schlüssel an, seine eigenen Wiederholungen senden daher nie doppelt, und der Server erweitert den erhaltenen Schlüssel pro Eintrag zu `key/0`, `key/1` und so weiter, getrennt durch einen Schrägstrich, ein Zeichen, das Ihr eigener Schlüssel nicht enthalten darf; ein Schlüssel über hundert Nachrichten kann sie daher nicht auf die erste zusammenfallen lassen.
emails[].fromRecipientInputerforderlich- Der Absender, als blanke Adresse, als `Name <addr@host>` oder als Objekt. Es gibt keinen Ersatzabsender und der Schlüssel muss für diese Adresse zugelassen sein; eine Ablehnung lässt nur diesen einen Eintrag scheitern, als `permission_error` mit dem Code `from_address_forbidden`.
emails[].toRecipientInput | RecipientInput[]erforderlich- Mindestens ein Empfänger, und ein einzelner wird vom Client in ein array verpackt. Höchstens 50 Adressen über `to`, `cc` und `bcc` zusammen, gezählt pro Nachricht und nicht über den Batch hinweg.
emails[].ccRecipientInput | RecipientInput[]- Standardmäßig keine, und zählt gegen dieselbe Gesamtzahl von 50 Adressen wie `to` und `bcc`.
emails[].bccRecipientInput | RecipientInput[]- Standardmäßig keine, und zählt gegen dieselbe Gesamtzahl von 50 Adressen. `Bcc` ist einer der Namen, die `headers` nicht setzen darf, dies ist daher der einzige Weg für eine Blindkopie. Die Header-Form würde den Umschlag pro Empfänger aufheben, der die Adresse verborgen hält.
emails[].replyToRecipientInput- Wohin Antworten gehen. Wird nach `headers` angewendet und überschreibt daher ein dort ebenfalls gesetztes `Reply-To`, statt ein zweites hinzuzufügen.
emails[].subjectstring- Höchstens 998 Zeichen, das Zeilenlimit von RFC 5322, Standard ist eine leere Zeichenkette. Ein leerer Betreff fällt auf den des Templates durch, wenn `template` einen liefert.
emails[].htmlstring- Der HTML-Teil, höchstens eine Million Zeichen, und der Teil, den Empfänger sehen, wenn beide Bodys angegeben sind. Eines von `html`, `text`, `template` oder `draftId` ist erforderlich, und ein Eintrag ohne eines davon scheitert als `validation_error` auf `html`.
emails[].textstring- Der Nur-Text-Teil, höchstens eine Million Zeichen. Beide dürfen gesendet werden, und jeder Transport auf diesem Weg baut einen Body aus einem String, `html` setzt sich daher durch, sofern vorhanden.
emails[].headersRecord<string, string>- Nur `X-*`, `List-*`, Reply-To, Precedence, Auto-Submitted, Importance, Priority und Feedback-ID; alles, was der Transport selbst setzt (From, To, Bcc, Subject, Message-ID, die DKIM- und ARC-Header), wird als `reserved_header` abgelehnt statt stillschweigend verworfen. Werte umfassen höchstens 998 Zeichen und dürfen kein CR, LF oder NUL enthalten, denn eine zweite Zeile ist ein zweiter Header.
emails[].attachmentsAttachmentInput[]- Höchstens 20 Dateien pro Nachricht, wobei eingebettete Dateien nach dem Dekodieren zusammen 5 MB ergeben dürfen, gezählt pro Nachricht und nicht pro Batch. `content` ist auf der Leitung base64; übergeben Sie Bytes und der Client kodiert sie, denn genau hier sprengt selbstgebautes base64 zuverlässig den Call-Stack. Ein Eintrag `{ fileId }` benennt eine Datei, die bereits im Workspace liegt, und zählt nicht gegen die Obergrenze für eingebettete Dateien.
emails[].threadIdstring- Antwort in einen bestehenden Thread, höchstens 256 Zeichen. Der Transport schreibt daraus In-Reply-To und References, was dafür sorgt, dass die Antwort in der Konversation landet und nicht daneben.
emails[].draftIdstring- Sendet den Inhalt eines gespeicherten Entwurfs unter diesem Umschlag, höchstens 256 Zeichen. Die hier gebauten Empfänger, der Betreff und die Header sind das, was auf die Leitung geht.
emails[].template{ id, version?, props?, slots? }- Rendert ein gespeichertes Template serverseitig, per id (`tpl_…`) oder slug, wobei `version` eine Revision festschreibt und `props`/`slots` es befüllen. Einmal aufgelöst, wenn der Eintrag angenommen wird, und zusammen mit `html`/`text` sowie mit `draftId` abgelehnt, da jedes davon eine zweite Antwort darauf ist, was die Nachricht enthält.
emails[].scheduledAtDate | string- Ein `Date`, ein ISO-8601-Zeitpunkt oder eine Dauer wie `PT1H`; mindestens eine Sekunde in der Zukunft und höchstens 365 Tage voraus. Einträge werden unabhängig voneinander geplant, ein Batch kann daher hundert verschiedene Sendezeitpunkte enthalten.
emails[].cancellableForSecondsnumber- Ein Rückgängig-Fenster in Sekunden bei einem sofortigen Versand, ein integer von 0 bis 900, Standard 0. Jeder Wert über 0 wird zusammen mit `scheduledAt` am selben Eintrag abgelehnt, da eine geplante Nachricht bis zum Versand ohnehin abbrechbar ist.
emails[].trackingTrackingRequest- `opens` und `clicks`, jeweils unabhängig voneinander optional und jeweils nur für diese eine Nachricht überschreibend. Ein weggelassener Schalter fällt auf die Einstellung der Adresse zurück, von der die Nachricht gesendet wird, andernfalls auf Alle Adressen, was aktiv ist, sofern es dort nicht abgeschaltet wurde.
emails[].tagsRecord<string, string>- Höchstens 10 Labels, Schlüssel mit 1 bis 64 Zeichen aus `A-Za-z0-9_-` und Werte bis 256 Zeichen. Sie werden an der Nachricht zurückgegeben und nie interpretiert: `emails.list` nimmt `status`, `from`, `limit` und `cursor` entgegen und sonst nichts, ein Tag ist daher etwas, das man an einer bereits vorliegenden Nachricht abliest, und kein Weg, sie zu finden.
emails[].translateSendTranslateOptions- Sendet diesen Eintrag in einer anderen Sprache, aufgelöst zum Zeitpunkt der Annahme, sodass genau die freigegebenen Worte hinausgehen. Höchstens 10 Einträge in einem Batch dürfen dies tragen: Jeder verbraucht mehrere Modellaufrufe und die Einträge laufen nacheinander, ein größerer Batch würde mitten im Versand abgebrochen. Darüber hinaus wird der gesamte Aufruf als `too_many_items` auf `emails` abgelehnt, bevor irgendetwas gesendet wird.
Antwort: BatchResultResource
itemsBatchItemResource[]- Ein Eintrag pro Eingabe, in der Reihenfolge, in der Sie sie gesendet haben. Nichts wird zurückgerollt, dies ist daher eine Aufzeichnung dessen, was mit jeder Nachricht geschah, und kein Bericht über eine Transaktion. Die API antwortet mit 207, ob alle, einige oder keine Nachricht angenommen wurde, das Promise löst daher in jedem Fall auf, und der `status` pro Eintrag ist das, worüber zu verzweigen ist.
sentnumber- Wie viele Einträge ANGENOMMEN wurden, was nicht dasselbe ist wie die Zahl der tatsächlich versendeten. Ein Eintrag kann `ok` sein und dennoch einen `email.status` von `failed` oder `partial` tragen, denn ein Transport, der die Nachricht nach dem Anlegen der Zeile ablehnt, ist ein Zustellergebnis und keine abgelehnte Anfrage.
failednumber- Wie viele Einträge einen `error` tragen. `failed > 0` ist eine Liste zum Abarbeiten und kein Grund, den Batch erneut zu senden. Die angenommenen Nachrichten sind bereits hinaus.
items[].indexnumber- Die Position, die die Nachricht dieses Eintrags in dem von Ihnen gesendeten array hatte. Wird zusätzlich zur Reihenfolge als Feld mitgeführt, damit Code, der `items` filtert oder sortiert, weiterhin sagen kann, welche Eingabe gescheitert ist.
items[].status'ok' | 'error'- Der Diskriminator der Union: `ok` trägt `email`, `error` trägt `error`, und kein Eintrag trägt beides.
items[].emailSentEmailResource- Die angenommene Nachricht, nur bei einem `ok`-Eintrag, in derselben Form, die ein einzelner Versand zurückgibt. Sie trägt keinen `tracking`-Schlüssel, denn Interaktionen werden später gemeldet und zum Zeitpunkt der Annahme gibt es nichts zu melden.
items[].email.replayedboolean- True, wenn der abgeleitete `Idempotency-Key` auf einen bereits existierenden Versand passte, es wurde also nichts Neues gesendet und dies ist die ursprüngliche Nachricht.
items[].error{ type: string; code: string; message: string; param?: string }- Warum genau diese Nachricht abgelehnt wurde, nur bei einem `error`-Eintrag. Es ist der Fehlerumschlag der API ohne `docUrl` und `requestId`: Diese beschreiben die Anfrage, und die Anfrage als Ganzes war erfolgreich.
items[].error.typestring- Die Kategorie, über die ein Client verzweigen darf: `validation_error`, `permission_error`, `not_found_error`, `conflict_error` und die übrigen. Die Menge ist eingefroren und wächst nicht, anders als `code`.
items[].error.codestring- Der konkrete Fehler: `from_address_forbidden`, `invalid_email_address`, `too_many_recipients`, `reserved_header`, `message_too_large`, `unknown_parameter`. Offen und erweiterbar, behandeln Sie einen Code, den Sie nicht kennen, daher als seinen `type`.
items[].error.messagestring- Ein Satz für Menschen, der den beanstandeten Wert nennt, sofern es einen gibt. Kein stabiler Bezeichner. Verzweigen Sie über `code`.
items[].error.paramstring- Das abgelehnte Feld, als Pfad mit Punkten innerhalb DIESER Nachricht: `to.0`, `from`, `attachments`. Nicht vorhanden, wenn der Fehler kein Feld nennt, und nie mit der Position im Batch vorangestellt, wofür `index` da ist.