03 · email api

Email API

標準HTTPで接続し、リクエスト、受付結果、メール状態を確認します。

1. 認証と接続先

送信・照会はAuthorization: Bearer <API Key>を使用します。originとプロキシ接頭辞は確認が必要です。ページの言語接頭辞をAPIパスに付けないでください。Keyはサーバー側で管理します。例は標準HTTPで、SMTPDog SDKではありません。

2. メールを1通送る

POST /v1/mail/sendはJSONを受け取ります。fromとtoは単一アドレス文字列で、配列ではありません。テンプレートなしではsubjectとtextまたはhtmlが必要です。cc、bcc、attachments、一括・予約送信には対応していません。

フィールド / 設定	型 / 状態	説明
from	string	送信者1件、Name <addr> 形式も可、検証済みドメイン、名前は100文字まで
to	string	受信者1件、配列不可
subject	string	テンプレートなしでは必須、CR/LF不可
html / text	string	テンプレートなしではどちらかの本文が必要。htmlとtextの両方の送信を推奨します。プレーンテキスト版があると迷惑メール判定されにくくなります
reply_to	string	任意、返信先メールボックス1件
headers	map<string,string>	任意、List-Unsubscribe・List-Unsubscribe-Post・Auto-Submittedのみ
template_id	uint64	任意、自分のテンプレートID
variables	map<string,string>	任意、文字列値の変数

curl -X POST "${SMTPDOG_API_ORIGIN}/v1/mail/send" \
  -H "Authorization: Bearer ${SMTPDOG_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "from": "sender@example.com",
    "to": "recipient@example.com",
    "subject": "Welcome to your product",
    "text": "Your message goes here."
  }'

3. 受付と状態照会

202はmessage_idとqueuedを返します。GET /v1/mail/{message_id}でアカウント所有の状態を照会します。created_atは必須、delivered_atとsmtp_responseは省略可能です。sentはノード受付の意味にもなり、受信箱・開封確認ではありません。ドメイン制限Keyでも照会はアカウント単位です。

フィールド / 設定	型 / 状態	説明
queued	string	キュー受付
sending	string	送信処理中
sent	string	ノード受付等、受信箱保証なし
deferred	string	一時遅延、後の状態を確認
bounced	string	バウンス
failed	string	送信失敗

{
  "message_id": "00000000-0000-4000-8000-000000000000",
  "status": "queued"
}

4. 既存テンプレートを使う

template_idは自分のアカウントのものを使います。subject、html、textはテンプレートに置換後、検証されます。variablesは文字列値です。{{name}}の単純置換で、未指定は残り、HTML値はエスケープされます。ループ・条件式はありません。実際に作成したIDを使ってください。

{
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "template_id": 123,
  "variables": {
    "name": "Example recipient"
  }
}

5. エラーと再試行

通常のエラーはcodeとerrorです。codeで判定し、errorの5言語対応はありません。権限・設定エラーを繰り返さないでください。タイムアウトしても受付済みの場合があります。冪等キーや再送APIがなく、重複送信・消費の可能性があります。失敗時の枠返還も保証されません。

フィールド / 設定	型 / 状態	説明
400 invalid_request	HTTP	型、件名、本文を確認
401 api_key_invalid	HTTP	Keyとアカウントを確認
403 domain_unverified / api_key_domain_forbidden / content_blocked	HTTP	検証・範囲・内容を確認
404 template_not_found / message_not_found	HTTP	IDと所有アカウントを確認
429 quota_exceeded	HTTP	総・日・時間上限を確認、無条件再試行しない
500 internal_error	HTTP	状況を保存して相談、部分処理の可能性あり