ナレッジベース
メール API
1 回の呼び出しで 1 通でも 100 通でも、今すぐでも後でも送れて、再試行しても二重送信になりません。
詳細
- POST /emails は 1 通を、POST /emails/batch は互いに独立した最大 100 通を送ります。バッチは全部か無しかにはなりません。7 番目の宛先が不正なら 7 番目だけが失敗し、残りは送られ、応答は項目ごとに結果を返します。
- 本文のソースはちょうど 1 つです。html と text の一方または両方、ID かスラッグで指定する保存済みテンプレート (文面の担当が別の人ならバージョンを固定)、または既存の下書き。タグは最大 10 個付けられ、読み取りのたびに返されます。
- scheduledAt は、ISO 8601 の日時か PT1H のような期間で、メッセージを最大 365 日保留します。cancellableForSeconds は即時送信に最大 900 秒の取り消し猶予を与えます。どちらも送られるまではキャンセルでき、予約送信は再予約もできます。
- すべての送信には、何かが送り出される前に確保される Idempotency-Key が付きます。そのためタイムアウト後の再試行では、最初の結果が Idempotency-Replayed: true 付きで返ります。同じキーで本文が違えば idempotency_key_reuse として拒否されます。
- 送信には受け付けた瞬間から msg_ ID があります。GET /emails/{id} で読み取り、/events で宛先ごとの履歴、/tracking で開封とクリックを確認できます。
- translate を付けると、メッセージは宛先の言語で配信されます。翻訳はリクエストの受け付け時に行われるので、予約送信は承認した文面のまま送られます。翻訳できない場合は原文に戻さず、送信を拒否します。
- 添付ファイル: 最大 20 個、埋め込みは合計 5 MB まで。それより大きいファイルは、ワークスペースのファイルを ID で指定して送り、ダウンロードリンクとして届きます。
- 未対応の点: テストモードはまだないため、どのキーでも実際に配信されます。また送信レコードにはバウンス状態がありません。バウンスはスレッドにラベルが付き、email.bounced Webhook として通知されますが、GET /emails では sent のままです。
- 配信停止リスト、つまり設定の「ブロック中のアドレス」は API にもある。GET /suppressions は検索と理由の絞り込みで読み、POST /suppressions は手作業でアドレスをブロックし、DELETE /suppressions/{id} は再び許可する。ただしハードバウンスは残る。SDK と MCP サーバーも同じことができ、変更のたびに suppression.added または suppression.removed の webhook が送られる。