Ruby

Planen und abbrechen

`scheduledAt`, `emails.reschedule`, `emails.update` und `emails.cancel`.

Später senden

schedule.rb

message = {from: "[email protected]", to: "[email protected]", subject: "Your September invoice", text: "Invoice attached."} client.emails.send(message, scheduledAt: "PT1H")client.emails.send(message, scheduledAt: Time.utc(2027, 1, 1, 9))client.emails.send(message, scheduledAt: "2027-01-01T09:00:00.000Z")

Ein Time oder DateTime, ein Zeitpunkt nach ISO 8601 als String oder eine Dauer wie PT1H oder P2D. Bis zu einem Jahr im Voraus, nie in der Vergangenheit. Ein Keyword-Argument neben dem Hash fügt das Feld einer Nachricht hinzu, die Sie zuvor gebaut haben.

Ein Ruby-Date wird als bloßes Datum wie 2027-01-01 gesendet, das die API als Mitternacht UTC an diesem Tag liest. Übergeben Sie ein Time, etwa Time.utc(2027, 1, 1, 9), wenn die Uhrzeit wichtig ist.

Verschieben und stoppen

reschedule.rb

message = {from: "[email protected]", to: "[email protected]", subject: "Your September invoice", text: "Invoice attached."} queued = client.emails.send(message, scheduledAt: "PT1H") client.emails.reschedule(queued[:id], Time.now + 86_400)client.emails.cancel(queued[:id])

Nur Nachrichten mit queued und scheduled lassen sich stoppen. Alles Weitergehende löst einen OpenEmail::ConflictError aus, denn ein Teil davon liegt bereits in jemandes Postfach. Das Abbrechen einer bereits abgebrochenen Nachricht gelingt und ändert nichts.

Um zu finden, was in einem Zeitfenster auf den Versand wartet, listen Sie mit status: ["scheduled", "queued"] sowie scheduled_from: und scheduled_to: auf, so wie es der Kalender der App tut.

Vor dem Versand ändern

emails.update ändert eine Nachricht, die noch nicht hinausgegangen ist: wann sie hinausgeht, mit scheduledAt, was sie sagt, mit subject, html und text, die Adresse, von der sie ausgeht, mit from, und an wen sie geht, mit to, cc und bcc. Senden Sie beliebige davon zusammen, und ein weggelassenes Feld behält seinen Wert. Eine Empfängerliste ersetzt die gespeicherte vollständig. Das entspricht dem Bearbeiten einer geplanten Nachricht im Kalender der App.

update.rb

updated = client.emails.update(  "msg_3f9a1c07d2b84e6a9c5b1f20",  subject: "Your September invoice, corrected",  to: ["[email protected]", "[email protected]"],  scheduledAt: Time.utc(2026, 10, 5, 8)) puts updated[:status], updated[:subject], updated[:scheduledAt]

from wird wie bei einem Versand geprüft, es muss also eine Adresse sein, als die der Schlüssel senden darf. Eine Nachricht, die beim Annehmen übersetzt wurde, behält ihren freigegebenen Wortlaut, ein neuer subject, html oder text für sie ergibt also einen 409 translation_locked, und eine, die vor dem Planen verschlüsselt wurde, behält ihren Wortlaut und ihre Empfänger. Brechen Sie solche Nachrichten stattdessen ab und senden Sie sie erneut.

Stattdessen ein Rückgängig-Fenster

undo_window.rb

message = {from: "[email protected]", to: "[email protected]", subject: "Your September invoice", text: "Invoice attached."} held = client.emails.send(message, cancellableForSeconds: 30) puts held[:status], held[:cancellableUntil]

Eine geplante Nachricht ist bis zum Versand ohnehin abbrechbar, beides lässt sich daher nicht kombinieren, und der Server lehnt es ab. Verwenden Sie dies für ein Rückgängig-Fenster bei einer sofortigen Nachricht.

Parameter: Terminierung

scheduledAtTime, DateTime or String: Wann gesendet wird, bei `emails.send`: ein Time oder DateTime, ein Zeitpunkt nach ISO 8601 als String oder eine Dauer wie `PT1H` oder `P2D`. Ein Time oder DateTime wird als UTC-Zeitpunkt gesendet, ein String unverändert und ein Ruby-Date als bloßes Datum, das Mitternacht UTC bedeutet. Mindestens eine Sekunde in der Zukunft und höchstens 365 Tage voraus, jede verletzte Grenze ergibt einen `validation_error` auf `scheduledAt`, und natürliche Sprache wird nicht akzeptiert, denn „nächsten Dienstag“ falsch zu deuten sendet eine Nachricht zu einer Zeit, die sich nicht zurückholen lässt.
cancellableForSecondsInteger: Ein Rückgängig-Fenster bei einem SOFORTIGEN Versand: ein Integer von 0 bis 900, Standard 0. Jeder Wert über 0 wird zusammen mit `scheduledAt` abgelehnt, das bis zum Versand ohnehin abbrechbar ist, und eine so zurückgehaltene Nachricht steht auf `queued` statt auf `scheduled`. Es ist derselbe Aufschubmechanismus mit kurzer Verzögerung.
idStringerforderlich: Die `msg_`-id und das erste Argument von `emails.cancel`, `emails.reschedule` und `emails.update`. Sie benötigen `emails:send` statt eines eigenen Scopes und suchen die id innerhalb des eigenen Workspace des Schlüssels. Eine id aus einem anderen ergibt daher genau wie eine nie existierende id einen `not_found_error`.
scheduled_atTime, DateTime or Stringerforderlich: Die neue Zeit, als zweites Argument von `emails.reschedule`, nach denselben Regeln und gegen dasselbe Ein-Jahres-Fenster gelesen. Sie ist das Einzige, was `reschedule` ändert, und der Client sendet nichts anderes. Eine Dauer ist relativ zu dem Zeitpunkt, zu dem der SERVER sie liest, eine wiederholte Neuterminierung landet daher etwas später als die erste: später, nie früher.
api_keyString: Handelt bei jedem der drei Aufrufe mit diesem Schlüssel statt mit dem des Clients.

Antwort

cancel, reschedule und update geben jeweils die gesamte Nachricht als Hash mit Symbol-Schlüsseln zurück.

objectString: Immer `email`. Diese Aufrufe antworten mit der gesamten Nachricht statt mit einer Bestätigung, es muss also nichts erneut geholt werden, um zu sehen, was sich geändert hat. `emails.send` gibt dieselbe Form plus `replayed` zurück.
idString: Das `msg_`-Handle. Stabil über die Lebensdauer der Nachricht und die id, die jeder andere Aufruf darauf entgegennimmt.
statusString: `cancelled` nach einem Abbruch und `scheduled` nach einer Neuterminierung, auch bei einer Nachricht, die nur hinter einem Rückgängig-Fenster `queued` war und die eine Neuterminierung in eine echte Terminierung verwandelt. Nur Nachrichten mit `queued` und `scheduled` lassen sich verschieben oder stoppen. Alles Weitergehende ergibt einen `conflict_error` mit dem Code `email_not_cancellable`, denn ein Teil davon liegt bereits in jemandes Postfach.
scheduledAtString or nil: Der Zeitpunkt nach ISO 8601, zu dem die Nachricht versendet werden soll. Gesetzt sowohl bei einem Rückgängig-Fenster als auch bei einem Versand mit `scheduledAt`, da beides ein Mechanismus ist, und nil bei einem einfachen sofortigen Versand.
cancellableUntilString or nil: Wann das Abbrechen nicht mehr funktioniert, derselbe Zeitpunkt wie `scheduledAt` auf beiden aufgeschobenen Wegen. nil bei einem sofortigen Versand, der bereits hinaus ist, wenn der Aufruf zurückkehrt.
sentAtString or nil: Wann die Nachricht tatsächlich hinausging. nil, solange sie wartet, und für immer nil bei einer abgebrochenen.
messageIdString or nil: Die Message-ID nach RFC 5322, nil, bis das MIME existiert, also immer nil bei einer Nachricht, auf die diese Aufrufe wirken können. Nichts, womit man die API anspricht, und auch nicht das, worüber ein späterer Bounce zurückkommt: Der Versanddienst schreibt den Header auf dem Weg hinaus um.
threadIdString or nil: Der Thread, zu dem diese Nachricht gehört, aus der Anfrage übernommen und mit dem überschrieben, was der Transport beim Senden meldet. nil, wenn es keine Antwort ist.
transportString or nil: Wie die Bytes hinausgingen, und nil bis zum Versand, also nil bei jeder Nachricht, die ein Abbruch oder eine Neuterminierung zurückgeben kann. Ein Versand im Testmodus erfasst `test`, und ein Transport, den dieses Gem noch nicht benennt, kann auftauchen. Behandeln Sie einen unbekannten Wert daher als Information und nicht als Fehler.
attemptsInteger: Wie oft der Versand diese Zeile beansprucht hat. Der Wert steigt mit jedem Beanspruchen, nicht mit einem erfolgreichen Versand, und ist 0 für alles, was noch wartet.
lastErrorString or nil: Der letzte zur Nachricht erfasste Fehler, nil, solange nichts fehlgeschlagen ist. Ein aufgeschobener Versand, dessen Job nicht eingereiht werden konnte, wird hier als `Could not schedule: …` geschrieben und auf `failed` gesetzt, was der einzige Weg ist, auf dem eine geplante Nachricht ohne Zutun aufhört, abbrechbar zu sein.
fromString: Die Adresse, unter der die Nachricht hinausgehen durfte: das gesendete `from`, bloß und in Kleinbuchstaben gespeichert. Jeder Anzeigename entfällt hier, weil der Filter `from:` von `emails.list` auf Gleichheit vergleicht.