返回首页

SMTPDog 开发者接入文档

清晰透明的接入规范:域名验证、SMTP 与 Email API、API Key、Webhook 验签与常见问题排查。

02 · smtp

SMTP 接入

保留已有 SMTP 客户端,通过加密连接发送单收件人邮件。

1. 连接参数

公网主机、端口和证书域名需由部署负责人确认。源码默认入口为 587 STARTTLS 和 465 隐式 TLS,但不能直接视为公网可用配置。AUTH PLAIN / LOGIN 的密码为 API Key;用户名为客户端所需标签,当前不参与身份校验。

字段 / 配置类型 / 状态说明
host / portconfiguration实际公网配置待确认,不直接采用源码默认值
TLSSTARTTLS / implicit先启用加密和证书验证,再认证
usernamestring客户端标签,当前不校验身份
passwordAPI Key完整 API Key,不是账户密码

2. 先加密,再认证

STARTTLS:连接后 EHLO,升级 TLS,再 EHLO 和 AUTH。隐式 TLS:从建立连接起启用 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 和 API Key;权限拒绝检查已验证发件域名和 Key 范围;额度拒绝检查当前总额、每日和每小时限制。451 通常为临时故障,452 可为额度或多收件人问题,550 可为内容或权限问题。SMTP 接收成功不代表最终投递,且不返回 HTTP message_id。