E-Mails planen und stornieren

Diese Seite erklärt, wie Sie eine E-Mail mit der E-Mail-API für später planen, wie Sie sie auf einen anderen Zeitpunkt verschieben und wie Sie eine E-Mail stornieren, bevor sie hinausgeht. Stornieren funktioniert auch bei E-Mails, die nicht geplant waren, solange sie noch nicht zugestellt wurden.

E-Mail planen

Fügen Sie einer Sendeanfrage scheduled_at hinzu. Die Antwort enthält "status": "scheduled" und den normalisierten Zeitpunkt in scheduled_at, und die E-Mail jedes Empfängers löst email.scheduled statt email.accepted aus.

scheduled_at akzeptiert diese Formate:

Ein Zeitpunkt, der jetzt oder in der Vergangenheit liegt, sendet die E-Mail sofort mit dem Status accepted.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <reminders@acme.com>",
    "to": "ada@example.com",
    "subject": "Your appointment is tomorrow",
    "text": "See you at 14:00.",
    "scheduled_at": "2026-10-05T09:00:00Z"
  }'

const email = await emailit.emails.send({
  from: 'Acme <reminders@acme.com>',
  to: 'ada@example.com',
  subject: 'Your appointment is tomorrow',
  text: 'See you at 14:00.',
  scheduled_at: '2026-10-05T09:00:00Z',
});

email = client.emails.send({
    "from": "Acme <reminders@acme.com>",
    "to": "ada@example.com",
    "subject": "Your appointment is tomorrow",
    "text": "See you at 14:00.",
    "scheduled_at": "2026-10-05T09:00:00Z",
})

$email = $emailit->emails()->send([
    'from' => 'Acme <reminders@acme.com>',
    'to' => 'ada@example.com',
    'subject' => 'Your appointment is tomorrow',
    'text' => 'See you at 14:00.',
    'scheduled_at' => '2026-10-05T09:00:00Z',
]);

Emailit bereitet eine geplante E-Mail bei der Anfrage vor, nicht zum Sendezeitpunkt. Die Vorlage wird gerendert, URL-Anhänge werden heruntergeladen und Credits werden im Voraus berechnet. Um den Inhalt zu ändern, stornieren Sie die E-Mail und senden Sie eine neue.

Sendezeitpunkt ändern

Verwenden Sie Geplante E-Mail aktualisieren (POST /emails/{id}) mit einem neuen scheduled_at. Es gelten dieselben Formate.

• Der Status der E-Mail muss scheduled sein.
• Ihr aktueller Sendezeitpunkt muss mehr als 3 Minuten entfernt sein.
• Der neue Sendezeitpunkt muss mehr als 3 Minuten in der Zukunft liegen.

curl https://api.emailit.com/v2/emails/em_33VtK8mRq1xZp7LwN4cY2bHsDfa \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-10-05T15:00:00Z" }'

await emailit.emails.update('em_33VtK8mRq1xZp7LwN4cY2bHsDfa', {
  scheduled_at: '2026-10-05T15:00:00Z',
});

client.emails.update("em_33VtK8mRq1xZp7LwN4cY2bHsDfa", {
    "scheduled_at": "2026-10-05T15:00:00Z",
})

$emailit->emails()->update('em_33VtK8mRq1xZp7LwN4cY2bHsDfa', [
    'scheduled_at' => '2026-10-05T15:00:00Z',
]);

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "status": "scheduled",
  "scheduled_at": "2026-10-05T15:00:00.000Z",
  "updated_at": "2026-10-01T10:02:44.193027Z",
  "message": "Email schedule has been updated successfully"
}

Anders als bei einem neuen Versand wird ein unlesbarer Zeitpunkt hier mit 422 Invalid scheduled_at abgelehnt. Eine Anfrage, die gegen die 3-Minuten-Regel verstößt oder eine nicht geplante E-Mail betrifft, schlägt mit 422 Cannot update email fehl. Eine Anfrage mit mehreren Empfängern erstellt pro Empfänger eine E-Mail. Verschieben Sie daher jede em_-ID aus der Zuordnung ids. In der Weboberfläche lässt sich der Sendezeitpunkt nicht ändern.

E-Mail stornieren

Sie können eine ausgehende E-Mail stornieren, solange sie einen dieser Status hat:

curl -X POST https://api.emailit.com/v2/emails/em_33VtK8mRq1xZp7LwN4cY2bHsDfa/cancel \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "status": "canceled",
  "in_flight": false,
  "message": "Email has been canceled and removed from the send queue."
}

Ist in_flight true, wurde die E-Mail storniert, aber ein Zustellversuch läuft möglicherweise bereits, und die Meldung lautet „The current delivery attempt may still complete; remaining retries were stopped.“ Ein Status, der sich nicht stornieren lässt, oder eine geplante E-Mail, deren Sendezeitpunkt weniger als 3 Minuten entfernt ist, gibt 422 Cannot cancel email zurück.

Eine Stornierung erstattet die Credits nicht zurück, die beim Senden der E-Mail per API berechnet wurden.

So funktioniert die Stornierung

Die Stornierung nimmt die E-Mail aus der Versandwarteschlange. Sie holt die E-Mail nicht aus dem Posteingang des Empfängers zurück.

1. Emailit prüft, ob sich die E-Mail noch stornieren lässt.
2. Es setzt den Status auf canceled, fügt dem Zustellverlauf der E-Mail einen Eintrag „Canceled“ hinzu und entfernt sie aus der Versandwarteschlange.
3. Hat ein Zustell-Worker die E-Mail bereits übernommen, prüft er den Status unmittelbar vor der Übergabe der Nachricht an den Server des Empfängers erneut und überspringt sie, wenn er canceled sieht.
4. Emailit löst email.canceled mit dem previous_status aus.

War die Nachricht bereits auf dem Weg zum Server des Empfängers, kann dieser Versuch trotzdem gelingen. Emailit behält den Status canceled bei, auch wenn der parallel laufende Versuch zugestellt wird oder bounct, aber der Empfänger erhält die Nachricht möglicherweise trotzdem. Verstehen Sie die Stornierung als „stoppen, bevor sie hinausgeht“, nicht als „Senden rückgängig machen“.

Status und Events

Eine geplante E-Mail löst email.accepted nicht aus, wenn ihr Sendezeitpunkt erreicht ist. Die vollständige Liste finden Sie unter E-Mail-Status.

Siehe auch

• Geplante E-Mail aktualisieren
• E-Mail stornieren
• E-Mail senden
• E-Mail-Status
• Warum hängt meine E-Mail in Accepted oder Scheduled fest?