Scheduling

Add scheduled_at to any send request to deliver later. The email is accepted immediately, gets the status scheduled and an email.scheduled webhook fires.

Formats

Format	Example
ISO 8601	2026-11-01T09:00:00Z, 2026-11-01T09:00:00+01:00
Natural language	in 30 seconds, in 10 minutes, in 2 hours, in 1 day, in 1 week

Natural language is in <number> <unit> where unit is one of second, sec, minute, min, hour, hr, day, week (plural s optional). The text is case-insensitive.

Other rules:

• Maximum 30 days in the future. Beyond that the API returns 422 validation_error.
• A time in the past, or less than about a second ahead, is treated as send now.
• ISO strings without a timezone offset are interpreted by the server’s date parser; always include Z or an offset.
• Both scheduled_at and scheduledAt are accepted.

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",
    },
)

Reschedule

Only emails with status scheduled can be changed. PATCH /emails/{id} replaces the time; a new job is queued and the old one becomes a no-op.

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" }

Cancel

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"

The status becomes canceled and the email is never sent. Cancelling or rescheduling an email that is no longer scheduled returns 422 validation_error (“Only scheduled emails can be canceled”).

Note

Recipients are counted against your quota when the email is accepted, not when it is sent. Cancelling does not currently refund quota.

Over SMTP

Set the X-SpacePost-Scheduled-At header to an ISO date or natural-language value. See SMTP relay.