Zeitplanung

Füge scheduled_at zu einer beliebigen Sendeanfrage hinzu, um später zuzustellen. Die E-Mail wird sofort angenommen, erhält den Status scheduled und ein email.scheduled-Webhook wird ausgelöst.

Formate

Format	Beispiel
ISO 8601	2026-11-01T09:00:00Z, 2026-11-01T09:00:00+01:00
Natürliche Sprache	in 30 seconds, in 10 minutes, in 2 hours, in 1 day, in 1 week

Natürliche Sprache hat die Form in <number> <unit>, wobei die Einheit eine von second, sec, minute, min, hour, hr, day, week ist (Plural-s optional). Groß- und Kleinschreibung spielt keine Rolle.

Weitere Regeln:

• Höchstens 30 Tage in der Zukunft. Darüber hinaus liefert die API 422 validation_error.
• Ein Zeitpunkt in der Vergangenheit oder weniger als etwa eine Sekunde in der Zukunft wird als sofort senden behandelt.
• ISO-Strings ohne Zeitzonen-Offset werden vom Datums-Parser des Servers interpretiert; gib immer Z oder einen Offset an.
• Sowohl scheduled_at als auch scheduledAt werden akzeptiert.

Node.js

schedule.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Your trial ends tomorrow",
  html: "<p>Reminder.</p>",
  scheduledAt: "in 1 day", // or an ISO date: "2026-11-01T09:00:00Z"
});

if (error) console.error(error);
else console.log("Scheduled", data.id);

cURL

curl -X POST https://api.spacepost.dev/emails \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Your trial ends tomorrow",
    "html": "<p>Reminder.</p>",
    "scheduled_at": "2026-11-01T09:00:00Z"
  }'

Python

requests.post(
    "https://api.spacepost.dev/emails",
    headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
    json={
        "from": "Acme <hello@acme.com>",
        "to": ["user@example.com"],
        "subject": "Your trial ends tomorrow",
        "html": "<p>Reminder.</p>",
        "scheduled_at": "in 1 day",
    },
)

Neu terminieren

Nur E-Mails mit dem Status scheduled lassen sich ändern. PATCH /emails/{id} ersetzt den Zeitpunkt; ein neuer Job wird eingereiht und der alte wird wirkungslos.

Node.js

reschedule.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { error } = await spacepost.emails.update({
  id: "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
  scheduledAt: "in 2 hours",
});
if (error) console.error(error);

cURL

curl -X PATCH https://api.spacepost.dev/emails/$EMAIL_ID \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-11-02T09:00:00Z" }'

Response (200)

{ "object": "email", "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" }

Stornieren

Node.js

cancel.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { error } = await spacepost.emails.cancel("0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10");
if (error) console.error(error); // 422 validation_error if it is no longer scheduled

cURL

curl -X POST https://api.spacepost.dev/emails/$EMAIL_ID/cancel -H "Authorization: Bearer $SPACEPOST_API_KEY"

Der Status wechselt auf canceled und die E-Mail wird nie gesendet. Wenn du eine E-Mail stornierst oder neu terminierst, die nicht mehr scheduled ist, erhältst du 422 validation_error (“Only scheduled emails can be canceled”).

Hinweis

Empfänger werden auf dein Kontingent angerechnet, wenn die E-Mail angenommen wird, nicht wenn sie gesendet wird. Eine Stornierung erstattet das Kontingent derzeit nicht.

Über SMTP

Setze den Header X-SpacePost-Scheduled-At auf ein ISO-Datum oder einen Wert in natürlicher Sprache. Siehe SMTP-Relay.