コンテンツにスキップ
spacepostドキュメント

メールを送信する

POST https://api.spacepost.dev/emails

最大 50 件の to 宛先に 1 通のメールを送信します。cc、bcc、添付ファイル、タグ、ヘッダー、送信スケジュールも指定できます。呼び出しは、メールが受理されてキューに入った時点ですぐに返ります。配信は非同期に行われ、結果は Webhook で通知されます。

例

Section titled “例”
send.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"],
  cc: ["manager@example.com"],
  bcc: ["archive@acme.com"],
  replyTo: "support@acme.com",
  subject: "Your invoice",
  html: "<p>Invoice attached.</p>",
  text: "Invoice attached.",
  headers: { "X-Entity-Ref-ID": "inv_1042" },
  tags: [{ name: "category", value: "invoice" }],
});


if (error) {
  console.error(error.statusCode, error.name, error.message);
} else {
  console.log("Email id:", data.id);
}
Response (200)
{ "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" }

リクエストボディ

Section titled “リクエストボディ”
fromstring必須

送信者。email@domain.com または Name <email@domain.com> の形式で指定します。ドメイン（または親ドメイン）が検証済みである必要があります。唯一の例外は onboarding@test.spacepost.dev で、詳しくは「テスト」をご覧ください。

tostring | string[]必須

宛先。最大 50 アドレス。

subjectstring必須

1 〜 998 文字。

htmlstring任意

HTML 本文。html と text の少なくとも一方が必須です。

textstring任意

プレーンテキスト本文。html だけを送信した場合は、テキスト版が自動生成され、到達率の向上に役立ちます。

ccstring | string[]任意

最大 50 アドレス。

bccstring | string[]任意

最大 50 アドレス。メッセージヘッダーには書き込まれません。

reply_tostring | string[]任意

最大 50 アドレス。キャメルケースの別名 replyTo も受け付けます。

scheduled_atstring任意

ISO 8601 形式の日時、または in 1 hour のような自然言語。最大 30 日先まで指定できます。別名は scheduledAt です。

headersobject任意

カスタムヘッダー。キーと値はどちらも文字列です。

attachmentsobject[]任意

最大 50 件の添付ファイル。それぞれに filename と、content または path のどちらか一方だけを指定します。

tagsobject[]任意

最大 50 個の { name, value } のペア。名前と値は A-Z a-z 0-9 _ - の 1 〜 256 文字です。

tenant_idstring任意

プラットフォームモード: テナントに代わって送信します（SpacePost の id またはご自身の external_id）。from のドメインがテナントに属している場合は省略できます。Node SDK での別名は tenantId です。詳しくは「プラットフォームモード」をご覧ください。

関連ページ: ドメインの検証、テスト、スケジュール送信、カスタムヘッダー、添付ファイル、タグ、プラットフォームモード。

どのフィールドのアドレスも、Name <email@domain.com> の形式で指定できます。

上限の一覧

Section titled “上限の一覧”
項目 上限
1 フィールドあたりの宛先数（to、cc、bcc、reply_to） 50
件名の長さ 998 文字
添付ファイル 1 通あたり 50 件、filename は最大 255 文字
タグ 1 通あたり 50 個、名前と値は A-Z a-z 0-9 _ - の 1 〜 256 文字
メッセージ全体のサイズ 添付ファイルとエンコードのオーバーヘッドを含めて 40 MB
スケジュール可能な期間 30 日
1 回のバッチリクエストあたりのメール数 100（バッチ送信）

レスポンス

Section titled “レスポンス”

成功すると 200 が返り、新しいメールの id（UUIDv7）が含まれます。この id を GET /emails/{id} に渡すと、メールとその last_event を取得できます。

失敗する主なケース

Section titled “失敗する主なケース”
ステータス name 意味
401 missing_api_key Authorization: Bearer ヘッダーがありません。
403 invalid_api_key キーが存在しない、無効化されている、または SpacePost のキー(sp_live_...)ではありません。
401 restricted_api_key ドメインを限定したキーが、別の from ドメインで使われました。
403 invalid_from_address from のドメインが、お使いのチームで検証されていません。
403 validation_error 送信元に test.spacepost.dev を使い、チームメンバーでもテスト用アドレスでもない宛先に送信しました。
403 sending_paused チームが一時停止されています。
422 validation_error フィールドが不足しているか、不正です。message にフィールド名が示されます。例: `to`: Invalid email address
429 daily_quota_exceeded 1 日の上限に達しました(新規アカウントのサンドボックス、信頼レベルごとの上限、またはテナントの daily_limit)。
429 monthly_quota_exceeded Free プランの月間上限に達しました。
429 rate_limit_exceeded 1 秒あたりのリクエスト数の上限を超えました。詳しくはレート制限をご覧ください。

完全な一覧はエラーをご覧ください。

呼び出しのあと

Section titled “呼び出しのあと”

メールは last_event として公開されるステータスを順に移ります。queued（またはスケジュール済みの scheduled）、sent、そのあとに delivered、delivery_delayed、bounced、complained、opened、clicked のいずれかです。すべての宛先が送信停止リストに載っている場合は、何も送信されず、ステータスは suppressed になります。