PHP

Planen und abbrechen

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

Später senden

schedule.php

$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' => new \DateTimeImmutable('2027-01-01 09:00', new \DateTimeZone('UTC'))]);$client->emails->send([...$message, 'scheduledAt' => '2027-01-01T09:00:00.000Z']);

Ein DateTimeInterface, ein Zeitpunkt nach ISO 8601 als String oder eine Dauer wie PT1H oder P2D. Bis zu einem Jahr im Voraus, nie in der Vergangenheit. Eine zuvor gebaute Nachricht in ein neues Array zu entpacken, mit scheduledAt daneben, fügt das Feld hinzu und lässt das Original unverändert.

Ein DateTimeInterface wird als Zeitpunkt in UTC gesendet, egal in welcher Zeitzone es erzeugt wurde, 09:00 in Europe/London geht also als genau der Zeitpunkt hinaus, den es bezeichnet. Ein Datums-String ohne Uhrzeit, etwa 2027-01-01, wird als Mitternacht UTC an diesem Tag gelesen. Übergeben Sie also einen Zeitpunkt, wenn die Uhrzeit wichtig ist.

Verschieben und stoppen

reschedule.php

$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'], new \DateTimeImmutable('+1 day'));$client->emails->cancel($queued['id']);

Nur Nachrichten mit queued und scheduled lassen sich stoppen. Alles Weitergehende wirft eine ConflictException, 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 scheduledFrom: und scheduledTo: 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.php

$updated = $client->emails->update('msg_3f9a1c07d2b84e6a9c5b1f20', [    'subject' => 'Your September invoice, corrected',    'to' => ['[email protected]', '[email protected]'],    'scheduledAt' => new \DateTimeImmutable('2026-10-05 08:00', new \DateTimeZone('UTC')),]); echo $updated['status'], ' ', $updated['subject'], ' ', $updated['scheduledAt'], PHP_EOL;

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.php

$message = [    'from' => '[email protected]',    'to' => '[email protected]',    'subject' => 'Your September invoice',    'text' => 'Invoice attached.',]; $held = $client->emails->send([...$message, 'cancellableForSeconds' => 30]); echo $held['status'], ' ', $held['cancellableUntil'], PHP_EOL;

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

scheduledAtDateTimeInterface or string: Wann gesendet wird, bei `emails->send`: ein `DateTimeInterface`, ein Zeitpunkt nach ISO 8601 als String oder eine Dauer wie `PT1H` oder `P2D`. Ein `DateTimeInterface` wird als UTC-Zeitpunkt gesendet und ein String unverändert, und ein Datums-String ohne Uhrzeit bedeutet Mitternacht UTC. 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.
cancellableForSecondsint: Ein Rückgängig-Fenster bei einem SOFORTIGEN Versand: ein int 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`.
$scheduledAtDateTimeInterface 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.
apiKeystring: Ein benanntes Argument bei jedem der drei Aufrufe. Handelt mit diesem Schlüssel statt mit dem des Clients.

Antwort

cancel, reschedule und update geben jeweils die gesamte Nachricht als Array mit den camelCase-Namen der API als 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 wirft eine `ConflictException`, deren `errorCode` `email_not_cancellable` ist, denn ein Teil davon liegt bereits in jemandes Postfach.
scheduledAtstring or null: 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 null bei einem einfachen sofortigen Versand.
cancellableUntilstring or null: Wann das Abbrechen nicht mehr funktioniert, derselbe Zeitpunkt wie `scheduledAt` auf beiden aufgeschobenen Wegen. null bei einem sofortigen Versand, der bereits hinaus ist, wenn der Aufruf zurückkehrt.
sentAtstring or null: Wann die Nachricht tatsächlich hinausging. null, solange sie wartet, und für immer null bei einer abgebrochenen.
messageIdstring or null: Die Message-ID nach RFC 5322, null, bis das MIME existiert, also immer null 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 null: Der Thread, zu dem diese Nachricht gehört, aus der Anfrage übernommen und mit dem überschrieben, was der Transport beim Senden meldet. null, wenn es keine Antwort ist.
transportstring or null: Wie die Bytes hinausgingen, und null bis zum Versand, also null bei jeder Nachricht, die ein Abbruch oder eine Neuterminierung zurückgeben kann. Ein Versand im Testmodus erfasst `test`, und ein Transport, den dieses Paket noch nicht benennt, kann auftauchen. Behandeln Sie einen unbekannten Wert daher als Information und nicht als Fehler.
attemptsint: 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 null: Der letzte zur Nachricht erfasste Fehler, null, 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.