返回首頁

SMTPDog 開發者串接文件

清晰透明的串接規範:網域驗證、SMTP 與 Email API、API Key、Webhook 驗簽與常見問題排查。

02 · smtp

SMTP 串接

保留既有 SMTP 用戶端,透過加密連線發送單收件者郵件。

1. 連線設定

公開主機、連接埠及憑證主機名稱須由部署負責人確認。原始碼預設為 587 STARTTLS 及 465 隱式 TLS,並非已驗證的公開設定。PLAIN / LOGIN 密碼為 API Key;使用者名稱是用戶端標籤,目前不參與身分驗證。

欄位 / 設定型別 / 狀態說明
host / portconfiguration公開設定待確認,不直接使用預設值
TLSSTARTTLS / implicit先加密及驗證憑證,再 AUTH
usernamestring用戶端標籤,目前不驗證身分
passwordAPI Key完整 API Key,非帳戶密碼

2. 先加密,再驗證

STARTTLS 順序為連線、EHLO、升級 TLS、再次 EHLO 與 AUTH。隱式 TLS 從建立連線起加密。必須驗證憑證,不可關閉驗證以繞過錯誤。明文連線不允許 AUTH。

SMTP_HOST=${SMTPDOG_SMTP_HOST}
SMTP_PORT=${SMTPDOG_SMTP_PORT}
SMTP_USERNAME=${SMTPDOG_SMTP_USERNAME}
SMTP_PASSWORD=${SMTPDOG_API_KEY}
SMTP_TLS_MODE=${SMTPDOG_SMTP_TLS_MODE}

3. 本文與收件者限制

每封郵件僅接受一個 RCPT TO,第二個會被拒絕。閘道擷取 Subject 與 text/html 後重新產生郵件,不完整保留附件及額外標頭,也不支援 CC/BCC。允許的副檔名不代表附件會送達。 此外,閘道會讀取 From 標頭中的顯示名稱(僅當位址與 MAIL FROM 一致時採用)、Reply-To,以及 List-Unsubscribe、List-Unsubscribe-Post、Auto-Submitted。

4. 排查串接問題

驗證失敗請檢查 TLS 與 Key;權限拒絕檢查已驗證網域及 Key 範圍;額度拒絕檢查總額、每日及每小時限制。451 常為暫時故障,452 可能是額度或多收件者問題,550 可能是內容或權限問題。SMTP 接收並非最終投遞,也不回傳 HTTP message_id。