スケジュール送信

どの送信リクエストにも scheduled_at を追加すると、後で配信できます。メールはすぐに受理されてステータスが scheduled になり、email.scheduled Webhook が発火します。

形式

形式	例
ISO 8601	`2026-11-01T09:00:00Z`、`2026-11-01T09:00:00+01:00`
自然言語	`in 30 seconds`、`in 10 minutes`、`in 2 hours`、`in 1 day`、`in 1 week`

自然言語は in <数値> <単位> の形式で、単位は second、sec、minute、min、hour、hr、day、week のいずれかです（複数形の s は省略できます）。大文字と小文字は区別されません。

その他のルールは次のとおりです。

未来の 最大 30 日先まで指定できます。それを超えると、API は 422 validation_error を返します。
過去の時刻、または約 1 秒未満先の時刻は、今すぐ送信として扱われます。
タイムゾーンのオフセットがない ISO 文字列は、サーバーの日付パーサーによって解釈されます。必ず Z かオフセットを付けてください。
scheduled_at と scheduledAt のどちらも受け付けます。

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

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

日時を変更する

変更できるのは、ステータスが scheduled のメールだけです。PATCH /emails/{id} で日時を置き換えます。新しいジョブがキューに入り、古いジョブは何も行わなくなります。

Node.js
cURL

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

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

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 -X POST https://api.spacepost.dev/emails/$EMAIL_ID/cancel -H "Authorization: Bearer $SPACEPOST_API_KEY"

ステータスが canceled になり、メールは送信されません。すでに scheduled ではないメールをキャンセルまたは日時変更しようとすると、422 validation_error（“Only scheduled emails can be canceled”）が返ります。

SMTP の場合

X-SpacePost-Scheduled-At ヘッダーに、ISO 形式の日時または自然言語の値を設定します。詳しくは SMTP リレーをご覧ください。