예약 발송

발송 요청에 scheduled_at을 추가하면 나중에 전달됩니다. 이메일은 즉시 접수되어 scheduled 상태가 되고 email.scheduled 웹훅이 호출됩니다.

형식

형식	예시
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 모두 허용됩니다.

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

일정 변경

상태가 scheduled인 이메일만 변경할 수 있습니다. PATCH /emails/{id}가 시각을 바꾸고, 새 작업이 큐에 들어가며 이전 작업은 아무 동작도 하지 않습니다.

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

취소

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"

상태가 canceled로 바뀌고 이메일은 발송되지 않습니다. 더 이상 scheduled 상태가 아닌 이메일을 취소하거나 일정을 변경하면 422 validation_error(“Only scheduled emails can be canceled”)가 반환됩니다.

참고

수신자는 이메일이 발송될 때가 아니라 접수될 때 할당량에 계산됩니다. 취소해도 현재는 할당량이 환불되지 않습니다.

SMTP로 사용하기

X-SpacePost-Scheduled-At 헤더에 ISO 날짜나 자연어 값을 설정하세요. SMTP 릴레이를 참고하세요.