Geplante E-Mails

Eine E-Mail planen

POST https://api.mail.land/v1/transactional/scheduled

Schedule an email

curl -X POST https://api.mail.land/v1/transactional/scheduled \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "[email protected]",
      "name": "Your App"
    },
    "to": {
      "email": "[email protected]",
      "name": "Jane Doe"
    },
    "subject": "Your trial expires tomorrow",
    "html": "<h1>Hi Jane,</h1><p>Your free trial expires tomorrow. Upgrade now to keep access.</p>",
    "text": "Hi Jane, Your free trial expires tomorrow. Upgrade now to keep access.",
    "scheduledAt": "2026-02-18T09:00:00Z",
    "timeZone": "America/New_York",
    "tags": ["trial-expiry", "reminder"]
  }'

Anforderungsfelder

Feld	Typ	Erforderlich	Beschreibung
`from`	Objekt	Ja	Absenderadresse (`email` und optionaler `name`)
`to`	Objekt	Ja	Einzelner Empfänger (`email` und optionaler `name`)
`subject`	Zeichenkette	Ja	E-Mail-Betreff
`html`	Zeichenkette	Bedingt	HTML-Inhalt (`html` oder `text` erforderlich)
`text`	Zeichenkette	Bedingt	Nur-Text-Inhalt
`replyTo`	Zeichenkette	Nein	Antwortadresse
`cc`	Array	Nein	CC-Empfänger (`email` und optionaler `name`)
`bcc`	Array	Nein	BCC-Empfänger (`email` und optionaler `name`)
`attachments`	Array	Nein	Dateianhänge (gleiches Format wie Einzelversand)
`headers`	Objekt	Nein	Benutzerdefinierte E-Mail-Header
`tags`	Array	Nein	Tags für Analysen
`scheduledAt`	Datum/Uhrzeit	Ja	Versandzeitpunkt. Wird immer als UTC interpretiert: senden Sie ihn mit `Z` oder einem expliziten Offset
`timeZone`	Zeichenkette	Nein	IANA-Zeitzone (z. B. `America/New_York`). Wird nur zur Anzeige gespeichert und zurückgegeben, beeinflusst nicht den tatsächlichen Versandzeitpunkt

scheduledAt muss in der Zukunft liegen und darf höchstens 7 Tage in der Zukunft liegen. Das Setzen von timeZone konvertiert scheduledAt nicht in diese Zone: der Zeitstempel wird immer als UTC gelesen. Ein Zeitpunkt in der Vergangenheit wird mit 400 VALIDATION_FAILED abgelehnt; mehr als 7 Tage im Voraus wird mit 400 INVALID_REQUEST abgelehnt ("Cannot schedule email more than 7 days in advance"). Dasselbe 7-Tage-Fenster gilt unabhängig davon, ob die Planung hier, über den Sende-Endpunkt oder per Neuplanung erstellt wird.

Beachten Sie die Unterschiede bei den Feldnamen gegenüber dem Sende-Endpunkt: Geplante E-Mails verwenden html/text (nicht htmlContent/textContent) und to ist ein einzelnes Objekt (kein Array).

Antwort

Status: 201 Created

Schedule response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "scheduledAt": "2026-02-18T09:00:00Z",
  "timeZone": "America/New_York",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": null,
  "messageIds": [],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

Status geplanter E-Mails

Status	Beschreibung
`pending`	Zur zukünftigen Zustellung in der Warteschlange
`processing`	Wird für den Versand verarbeitet
`sent`	Erfolgreich versendet
`failed`	Versand fehlgeschlagen (siehe Feld `error`)
`cancelled`	Vor dem Versand storniert

Geplante E-Mails auflisten

GET https://api.mail.land/v1/transactional/scheduled?limit=20

List scheduled emails

curl https://api.mail.land/v1/transactional/scheduled?limit=20 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

Nach Status filtern:

GET https://api.mail.land/v1/transactional/scheduled?status=pending

List scheduled emails by status

curl "https://api.mail.land/v1/transactional/scheduled?status=pending" \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

List response

{
  "items": [
    {
      "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "pending",
      "scheduledAt": "2026-02-18T09:00:00Z",
      "timeZone": "America/New_York",
      "to": "[email protected]",
      "recipientCount": 1,
      "subject": "Your trial expires tomorrow",
      "createdAt": "2026-02-17T10:00:00Z",
      "processedAt": null,
      "messageIds": [],
      "rejectedRecipients": [],
      "reasonCode": null,
      "error": null
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Abfrageparameter:

Parameter	Typ	Standard	Beschreibung
`cursor`	Zeichenkette	-	Opaker Cursor aus dem `nextCursor` der vorherigen Seite. Für die erste Seite weglassen.
`limit`	Ganzzahl	20	Elemente pro Seite (max. 100)
`status`	Zeichenkette	-	Nach Status filtern: `pending`, `processing`, `sent`, `failed`, `cancelled`

Eine geplante E-Mail abrufen

GET https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Get a scheduled email

curl https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

Detail response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "sent",
  "scheduledAt": "2026-02-18T09:00:00Z",
  "timeZone": "America/New_York",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": "2026-02-18T09:00:02Z",
  "messageId": "t_a1b2c3d4e5f6...",
  "messageIds": ["t_a1b2c3d4e5f6..."],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

Nach dem Versand enthält die Antwort processedAt (Versandzeitpunkt) und messageId (zur Verfolgung von Zustellungsereignissen).

Eine geplante E-Mail stornieren

DELETE https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Cancel a scheduled email

curl -X DELETE https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

Gibt bei Erfolg 204 No Content zurück. Sie können nur E-Mails mit Status pending stornieren. Der Versuch, eine E-Mail mit Status processing, sent oder failed zu stornieren, gibt 400 Bad Request zurück.

Eine E-Mail neu planen

Ändern Sie den Zustellzeitpunkt einer ausstehenden E-Mail:

PATCH https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Reschedule an email

curl -X PATCH https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledAt": "2026-02-19T14:00:00Z",
    "timeZone": "Europe/London"
  }'

Reschedule response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "scheduledAt": "2026-02-19T14:00:00Z",
  "timeZone": "Europe/London",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": null,
  "messageIds": [],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

Es gelten dieselben Planungsbeschränkungen: der neue Zeitpunkt muss in der Zukunft liegen und darf höchstens 7 Tage ab jetzt liegen, sonst wird die Anfrage mit 400 INVALID_REQUEST abgelehnt.

Zeitzonenverarbeitung

scheduledAt wird immer als UTC interpretiert, unabhängig davon, ob Sie eine timeZone angeben: senden Sie ihn mit Z oder einem expliziten Offset. timeZone wird nur zur Anzeige in Antworten gespeichert und zurückgegeben; MailLand konvertiert scheduledAt nicht in diese Zeitzone. Verwenden Sie IANA-Zeitzonenbezeichner, wenn Sie sie zur Anzeige festhalten möchten:

America/New_York
Europe/London
Asia/Tokyo
Australia/Sydney

Planung über den Sende-Endpunkt

Sie können E-Mails auch direkt über den regulären Sende-Endpunkt planen, indem Sie das Feld scheduledAt einfügen:

Schedule via send endpoint

{
  "from": { "email": "[email protected]" },
  "to": [{ "email": "[email protected]" }],
  "subject": "Scheduled email",
  "htmlContent": "<p>This will be sent later.</p>",
  "scheduledAt": "2026-02-18T09:00:00Z"
}

Die 202-Antwort des Sende-Endpunkts enthält scheduleId und scheduledAt. Diese Planung ist dieselbe Art von Datensatz, mit der die Endpunkte dieser Seite arbeiten: sie kann mit den oben beschriebenen Endpunkten aufgelistet, abgerufen, storniert und neu geplant werden, genau wie eine direkt über /v1/transactional/scheduled erstellte Planung. Das 7-Tage-Fenster (siehe Hinweis oben) gilt auch hier: Ein scheduledAt mehr als 7 Tage im Voraus wird mit 400 INVALID_REQUEST abgelehnt.

Nächste Schritte

REST API: sofortiger E-Mail-Versand
Templates: Templates über /v1/transactional/send mit scheduledAt verwenden
Batch-Versand: Batch-Versand planen

Geplante E-Mails

Eine E-Mail planenLink zum Abschnitt kopieren

AnforderungsfelderLink zum Abschnitt kopieren

AntwortLink zum Abschnitt kopieren

Status geplanter E-MailsLink zum Abschnitt kopieren

Geplante E-Mails auflistenLink zum Abschnitt kopieren

Eine geplante E-Mail abrufenLink zum Abschnitt kopieren

Eine geplante E-Mail stornierenLink zum Abschnitt kopieren

Eine E-Mail neu planenLink zum Abschnitt kopieren

ZeitzonenverarbeitungLink zum Abschnitt kopieren

Planung über den Sende-EndpunktLink zum Abschnitt kopieren

Nächste SchritteLink zum Abschnitt kopieren

Auf dieser Seite