Ruby

Einen Batch senden

`emails.send_batch`: bis zu 100 Nachrichten, Ergebnisse pro Eintrag.

emails.send_batch

send_batch.rb

invoices = [  {number: "INV-1042", email: "[email protected]"},  {number: "INV-1043", email: "[email protected]"}] messages = invoices.map do |invoice|  {from: "[email protected]", to: invoice[:email], subject: "Invoice #{invoice[:number]}", text: "Your invoice is attached."}end result = client.emails.send_batch(messages, idempotency_key: "invoices:2026-09") puts "#{result.sent} sent, #{result.failed} failed" result.items.each do |item|  if item[:status] == "error"    warn "#{item[:index]} #{item.dig(:error, :code)} #{item.dig(:error, :message)}"  else    puts "#{item[:index]} #{item.dig(:email, :id)}"  endend

send_batch nimmt ein Array von Nachrichten-Hashes, jeder genau wie der Body von emails.send aufgebaut, und gibt ein OpenEmail::BatchResult zurück. Seine items enthalten einen Hash pro Nachricht, 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, ein failed-Wert über 0 ist daher eine Liste zum Abarbeiten und kein Grund, den Batch erneut zu senden.

Ein Idempotency-Key deckt den Batch ab, und der Server erweitert ihn für jeden Eintrag. Ein wiederholter Batch spielt daher jede Nachricht erneut ab, statt sie auf die erste zusammenfallen zu lassen. Senden Sie bei einer Wiederholung dasselbe Array in derselben Reihenfolge: Ein verschobener Eintrag ist an den Key einer anderen Position gebunden und kommt als Fehler idempotency_key_reuse zurück.

Eine abgelehnte Nachricht löst keinen Fehler aus. Nur ein Problem mit dem Batch als Ganzem löst einen aus: ein leeres Array, mehr als 100 Nachrichten, mehr als 10 mit translate, ein Schlüssel- oder Scope-Fehler oder ein Serverfehler. Ein Serverfehler mittendrin tritt auf, nachdem die früheren Einträge bereits hinaus sind, und der Client wiederholt den Aufruf mit demselben Key, der diese Einträge erneut abspielt, statt sie zweimal zu senden.

Die Einträge werden innerhalb einer einzigen Anfrage nacheinander gesendet, ein großer Batch sofortiger Versände dauert daher deutlich länger als ein einzelnes send. Bemessen Sie das timeout: des Clients großzügig.

Parameter: emails.send_batch

emailsArray<Hash>erforderlich: Eine bis 100 Nachrichten, gesendet als `{"emails": [...]}` und einzeln in der angegebenen Reihenfolge angenommen. Jede durchläuft dieselbe Verarbeitung wie bei `emails.send`: Ein einzelner Empfänger wird verpackt, ein Time wird zu einem Zeitpunkt, und die Bytes von Anhängen werden kodiert. Ein leeres Array, mehr als 100 Nachrichten oder mehr als 10 Nachrichten mit `translate` lassen den gesamten Aufruf mit einem `validation_error` auf `emails` scheitern. Ein fehlender Scope `emails:send` und ein fehlerhafter `idempotency_key:` lassen ebenfalls den gesamten Aufruf scheitern, bevor eine einzige Nachricht gesendet wird.
idempotency_keyString: Dedupliziert den Batch prozessübergreifend. Der Client hängt ohnehin bei jedem Aufruf einen frisch erzeugten Key an, seine eigenen Wiederholungen senden daher nie doppelt, und der Server erweitert den erhaltenen Key für jeden Eintrag zu `key/0`, `key/1` und so weiter, getrennt durch einen Schrägstrich, ein Zeichen, das Ihr eigener Key nicht enthalten darf. Ein Key über hundert Nachrichten kann sie daher nicht auf die erste zusammenfallen lassen.
api_keyString: Sendet den Batch mit diesem Schlüssel statt mit dem des Clients.

Jede Nachricht in emails

fromString or Hasherforderlich: Der Absender, als bloße Adresse, als `Name <addr@host>` oder als Hash mit `email` und `name`. 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`.
toString, Hash or Arrayerforderlich: 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.
ccString, Hash or Array: Standardmäßig keine, und zählt gegen dieselbe Gesamtzahl von 50 Adressen wie `to` und `bcc`.
bccString, Hash or Array: 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.
replyToString or Hash: Wohin Antworten gehen. Wird nach `headers` angewendet und überschreibt daher ein dort ebenfalls gesetztes `Reply-To`, statt ein zweites hinzuzufügen.
subjectString: Höchstens 998 Zeichen, das Zeilenlimit von RFC 5322, Standard ist ein leerer String. Ein leerer Betreff fällt auf den des Templates durch, wenn `template` einen liefert.
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`.
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.
headersHash: 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.
attachmentsArray<Hash>: 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 die Bytes als binären String, IO oder Pathname, und der Client kodiert sie. Ein Hash nur mit `fileId` benennt eine Datei, die bereits im Workspace liegt, und zählt nicht gegen die Obergrenze für eingebettete Dateien.
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.
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.
templateHash: Rendert ein gespeichertes Template serverseitig, per id (`tpl_…`) oder Slug, wobei `version` eine Revision festschreibt und `props` und `slots` es befüllen. Einmal festgelegt, wenn der Eintrag angenommen wird, und zusammen mit `html` oder `text` sowie mit `draftId` abgelehnt, da jedes davon eine zweite Antwort darauf ist, was die Nachricht enthält.
scheduledAtTime, DateTime or String: Ein Time oder DateTime, ein Zeitpunkt nach ISO 8601 oder eine Dauer wie `PT1H`, mindestens eine Sekunde in der Zukunft und höchstens 365 Tage voraus. Ein Ruby-Date bedeutet Mitternacht UTC an diesem Tag. Einträge werden unabhängig voneinander geplant, ein Batch kann daher hundert verschiedene Sendezeitpunkte enthalten.
cancellableForSecondsInteger: Ein Rückgängig-Fenster in Sekunden bei einem sofortigen Versand, 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.
trackingHash: `opens` und `clicks`, jeweils optional und jeweils nur für diese eine Nachricht überschreibend. Ein weggelassener Schlüssel folgt der Adresse, von der die Nachricht gesendet wird (oder dem Catch-all, der sie aufgefangen hat), was inaktiv ist, sofern diese Adresse es nicht eingeschaltet hat.
tagsHash: Höchstens 10 Labels, mit Schlüsseln aus 1 bis 64 Zeichen aus `A-Za-z0-9_-` und Werten bis 256 Zeichen. Sie werden an der Nachricht zurückgegeben und nie interpretiert: `emails.list` filtert nach `status:`, `from:`, `broadcast_id:` und dem Planungsfenster und nach nichts sonst. Ein Tag ist daher etwas, das man an einer bereits vorliegenden Nachricht abliest, und kein Weg, sie zu finden.
translateHash: Sendet diesen Eintrag in einer anderen Sprache, festgelegt 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: OpenEmail::BatchResult

itemsArray<Hash>: Ein Hash pro Nachricht, 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. Der Aufruf kehrt daher in jedem Fall zurück, und der `status` jedes Eintrags ist das, worüber zu verzweigen ist.
sentInteger: Wie viele Einträge ANGENOMMEN wurden, was nicht dasselbe ist wie die Zahl der tatsächlich versendeten. Ein Eintrag kann `ok` sein und dennoch eine `email` tragen, deren `status` `failed` oder `partial` ist, denn ein Transport, der die Nachricht nach dem Anlegen der Zeile ablehnt, ist ein Zustellergebnis und keine abgelehnte Anfrage.
failedInteger: Wie viele Einträge einen `error` tragen. Ein Wert über 0 ist eine Liste zum Abarbeiten und kein Grund, den Batch erneut zu senden. Die angenommenen Nachrichten sind bereits hinaus.

Jeder Eintrag

indexInteger: Die Position, die die Nachricht dieses Eintrags in dem von Ihnen gesendeten Array hatte. Wird zusätzlich zur Reihenfolge als Schlüssel mitgeführt, damit Code, der `items` filtert oder sortiert, weiterhin sagen kann, welche Nachricht gescheitert ist.
statusString: `ok` oder `error`. `ok` trägt `email`, `error` trägt `error`, und kein Eintrag trägt beides.
emailHash: Die angenommene Nachricht, nur bei einem `ok`-Eintrag, in derselben Form, die ein einzelner Versand zurückgibt. Ihr `replayed` ist true, wenn der abgeleitete `Idempotency-Key` auf einen bereits existierenden Versand passte. Dann wurde nichts Neues gesendet, und dies ist die ursprüngliche Nachricht. Sie trägt keinen `tracking`-Schlüssel, denn Interaktionen werden später gemeldet und zum Zeitpunkt der Annahme gibt es nichts zu melden.
errorHash: 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.

Der Fehler eines Eintrags

typeString: Die Kategorie, über die verzweigt wird: `validation_error`, `permission_error`, `not_found_error`, `conflict_error` und die übrigen. Die Menge ist eingefroren und wächst nicht, anders als `code`.
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`.
messageString: Ein Satz für Menschen, der den beanstandeten Wert nennt, sofern es einen gibt. Kein stabiler Bezeichner. Verzweigen Sie über `code`.
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.