一斉配信

一斉配信は、オーディエンスの購読中のすべてのコンタクトに 1 通のメッセージを送信します。SpacePost はこれをコンタクトごとにパーソナライズした 1 通ずつのメールに展開し、配信停止リンクと List-Unsubscribe ヘッダーを追加し、送信停止中のアドレスをスキップし、他のメールと同じようにすべてを追跡します。

ライフサイクル

ステータス	意味
`draft`	作成済みで、編集できます。まだ送信されていません。
`queued`	`send` が呼び出され、開始時刻（即時、または `scheduled_at`）を待っています。
`sending`	コンタクトへ展開中です。
`sent`	すべてのメールが配信のために受理されました。`sent_at` が設定されます。
`failed`	展開が停止しました。たとえば、クォータに達した、またはチームが一時停止された場合です。
`canceled`	送信前にキャンセルされました。

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

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
const audienceId = "0192e1c4-0000-7000-8000-0000000000a1";

// 1. Create a draft
const { data: draft, error } = await spacepost.broadcasts.create({
  audienceId,
  name: "October newsletter",
  from: "Acme <news@acme.com>",
  replyTo: "support@acme.com",
  subject: "What's new at Acme, {{{FIRST_NAME|friend}}}",
  previewText: "Three things we shipped this month",
  html: `
    <h1>Hi {{{FIRST_NAME|there}}},</h1>
    <p>Here is what is new.</p>
    <p><a href="{{{SPACEPOST_UNSUBSCRIBE_URL}}}">Unsubscribe</a></p>
  `,
});
if (error) throw new Error(error.message);

// 2. Send it now, or schedule it
const { error: sendError } = await spacepost.broadcasts.send(draft.id, { scheduledAt: "in 1 hour" });
if (sendError) throw new Error(sendError.message);

// 3. Check progress
const { data: broadcast } = await spacepost.broadcasts.get(draft.id);
console.log(broadcast?.status); // "queued" | "sending" | "sent" | "failed"

一斉配信を作成する

POST /broadcasts は下書きを作成し、{ "id": "..." } を返します。

audience_idstring (uuid)必須

送信先のオーディエンス。

fromstring必須

検証済みドメインの送信者。

subjectstring必須

1 〜 998 文字。プレースホルダーを使えます。

htmlstring任意

HTML 本文。送信する前に、html、text、またはその両方を指定してください。

textstring任意

プレーンテキスト本文。

reply_tostring | string[]任意

最大 50 アドレス。

preview_textstring任意

最大 200 文字。受信トレイで件名の後ろに表示されます。非表示のプリヘッダーとして挿入されます。

namestring任意

最大 100 文字。社内向けのラベル。

更新と削除

PATCH /broadcasts/{id} は同じフィールド（すべて任意）を受け付け、下書きに対してのみ動作します。DELETE /broadcasts/{id} は、下書きと、未来にスケジュールされている一斉配信に対して動作します。

# now
curl -X POST https://api.spacepost.dev/broadcasts/$ID/send -H "Authorization: Bearer $SPACEPOST_API_KEY"

# scheduled (ISO or natural language, up to 30 days ahead)
curl -X POST https://api.spacepost.dev/broadcasts/$ID/send \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-11-01T09:00:00Z" }'

await spacepost.broadcasts.send(id);                              // now
await spacepost.broadcasts.send(id, { scheduledAt: "in 1 hour" }); // later

送信できるのは、html または text の本文を持ち、検証済みドメインから送信する下書きだけです。レスポンスは { "id": "..." } です。

送信準備のチェック

送信する前に GET /broadcasts/{id}/readiness を呼ぶと、到達率のチェックリストが返ります（ダッシュボードのエディターにも同じリストが表示されます）。これは SpacePost の拡張機能で、Resend の API にはありません。

{ "ready": true, "checks": [{ "id": "html_size", "level": "warn", "title": "Gmail will clip this message", "detail": "..." }] }

チェック	レベル	条件
`sender_domain`	error	`from` のドメインがない、または検証されていません。
`dmarc`	warn	`_dmarc.<domain>` に `v=DMARC1` のレコードがない、または参照に失敗しました。`p=none` は合格です。
`subject`	error / warn	空の場合は error。すべて大文字、`!!!` や `$$$`、または 90 文字を超える場合は warning。
`html_size`	warn	HTML が 102 KB を超えています。Gmail が切り詰めるサイズです。
`images`	warn	画像のみ、またはテキストが少なく画像が 4 枚以上あります。
`shorteners`	warn	bit.ly、tinyurl.com、t.co などの短縮 URL を経由したリンクです。
`spam_phrases`	warn	件名または本文に、よくあるスパム特有の表現があります。
`unsubscribe`	ok	本文にプレースホルダーがない場合は配信停止のフッターが自動で追加されるため、これが送信を妨げることはありません。
`audience`	error	購読中のコンタクトがいません。
`role_addresses`	warn	コンタクトの 20% 超が、`info@` や `admin@` のようなアドレスです。

いずれかのチェックのレベルが error の場合、ready は false になります。その状態で送信すると、修正すべき点を列挙した validation_error（422）で失敗します。warning が送信を妨げることはありません。

一斉配信のメールには List-Id ヘッダーと Feedback-ID ヘッダー（<broadcast id>:<team id>:broadcast:spacepost）も付きます。これにより、Gmail Postmaster Tools が苦情を一斉配信に関連付けられます。トランザクションメールには付きません。

受信者に届くもの

パーソナライズは、subject、html、text に適用されます(パーソナライズ)。
配信停止: 本文に {{{SPACEPOST_UNSUBSCRIBE_URL}}} / {{{RESEND_UNSUBSCRIBE_URL}}} のプレースホルダーがない場合は、配信停止のフッターが自動で追加されます。List-Unsubscribe ヘッダーと List-Unsubscribe-Post: List-Unsubscribe=One-Click ヘッダーは、常に追加されます。
プレビューテキストは、HTML の先頭に非表示のプリヘッダーとして挿入されます。
配信停止したコンタクトと、送信停止リストに載っているアドレスはスキップされます。

クォータと上限

受信者 1 人につき、プランのクォータを 1 通分消費します。新規アカウントには、1 日 100 通のサンドボックスが適用されます。送信の途中でクォータを使い切ると、一斉配信は failed で終了します。すでに作成されたメールは、そのまま配信されます。ワーカーが再起動しても、展開は再開できます。

一斉配信の各メールは通常のメールです。GET /emails に表示され、Webhook のペイロードに broadcast_id が含まれ、バウンスしたり開封されたりします。