03 · email api

Email API

使用標準 HTTP 串接，檢視請求欄位、接收結果與郵件狀態。

1. 驗證與位址

發送與查詢使用 Authorization: Bearer <API Key>。API origin 及代理前綴待確認；頁面語言前綴不可加入 API 路徑。Key 只在伺服器端保管。此為標準 HTTP 範例，沒有 SMTPDog SDK。

2. 發送單封郵件

POST /v1/mail/send 接受 JSON。from 與 to 均為單一地址字串，不可使用陣列。非範本發送需非空 subject，且 text 或 html 至少一項。目前不支援 cc、bcc、attachments、批次或排程發送。

欄位 / 設定	型別 / 狀態	說明
from	string	單一寄件人，可寫成 Name <addr>；網域須已驗證，名稱最長 100 字元
to	string	單一收件地址、非陣列
subject	string	非範本必填，不可含 CR/LF
html / text	string	非範本至少一種非空本文；建議同時提供 html 與 text，純文字備份有助於降低被判為垃圾郵件的機率
reply_to	string	選填，單一回覆信箱
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 目前不是五語言協定。不要重複提交權限或設定錯誤。逾時仍可能已接收，目前沒有冪等鍵或重發介面，重送可能重複發送及扣額。失敗請求也不保證返還計數。

欄位 / 設定	型別 / 狀態	說明
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	保留錯誤情境並聯絡支援，可能已部分處理

繼續閱讀 — 常見問題