SMTP 与 API 接入

发信域名验证通过后，就可以创建凭证，让应用程序通过 SMTP 发信，并用 Webhook 和邮件记录跟踪投递结果。本文所有操作都在订阅详情页（/tm/<订阅 ID>）的各个标签页中完成。

#创建凭证

凭证属于某个邮件服务器，有两种类型：

操作步骤：

1. 进入订阅详情页，切换到 Credentials 标签页。
2. 用顶部下拉框选择邮件服务器，点击创建凭证。
3. 填写 Mail Server、Credential Name（如 Production API Key），Type 选择 SMTP Credential 或 API Key。
4. 提交后弹窗会显示新凭证的密钥，请立即复制并妥善保存。

凭证列表的 Key 列默认隐藏密钥，点击眼睛图标可以显示，点击复制图标可以复制。不再使用的凭证可以在 Delete this credential? 确认后删除，删除后用它认证的应用将立即无法发信。

#SMTP 设置

在 Credentials 标签页顶部的 SMTP Settings 区域可以看到当前邮件服务器的连接参数：

认证信息：

• 用户名：邮件服务器的 Token，在 Mail Servers 标签页的 Token 列中查看。
• 密码：类型为 SMTP Credential 的凭证密钥。

发件人地址（From）必须使用已在 Domains 中验证通过的域名。

#用 swaks 发一封测试邮件

swaks --server <Host>:<Port> --tls \
  --auth LOGIN \
  --auth-user '<邮件服务器 Token>' \
  --auth-password '<SMTP 凭证密钥>' \
  --from noreply@example.com \
  --to you@example.net \
  --header 'Subject: Test from Transactional Mail' \
  --body 'Hello'

#在应用中配置（以 Python 为例）

import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "noreply@example.com"
msg["To"] = "you@example.net"
msg["Subject"] = "Welcome"
msg.set_content("Thanks for signing up.")

with smtplib.SMTP("<Host>", <Port>) as s:
    s.starttls()
    s.login("<邮件服务器 Token>", "<SMTP 凭证密钥>")
    s.send_message(msg)

如果控制台给出的端口要求连接一开始就使用 TLS（隐式 TLS），请改用 smtplib.SMTP_SSL，并去掉 starttls()。

#API 方式发信

类型为 API Key 的凭证用于 API 方式发信。API 的接入地址目前没有在控制台中展示，如需使用请联系技术支持获取接入地址和请求格式。

#Live 与 Development 模式

创建邮件服务器时选择的 Mode 会影响投递行为：

• Live (Production)：正常投递到收件人。
• Development (Testing)：用于联调测试，邮件通常不会真正投递给外部收件人。请在 Messages 标签页查看结果。

正式上线前，确认应用使用的是 Live 模式邮件服务器的凭证。

#Webhook 事件通知

Webhook 会在邮件事件发生时，向你指定的 URL 发送 HTTP 请求，方便你在业务系统中记录送达、退信等状态。

1. 切换到 Webhooks 标签页，选择邮件服务器，点击新建。

2. 填写 Webhook Name 和 Webhook URL（如 https://your-server.com/webhook）。

3. Events：打开 All Events 订阅所有事件，或者关闭后在 Select Events 中勾选：

   事件	含义
   Message Sent	邮件已发出
   Message Delivered	邮件已送达
   Message Delayed	投递延迟，将重试
   Message Bounced	邮件被退回
   Message Held	邮件被暂扣
   Link Clicked	收件人点击了邮件中的链接
   Domain DNS Error	发信域名 DNS 配置出现问题

4. 保存后可以用测试按钮向该 URL 发送一次测试请求。编辑 Webhook 时可以通过 Enabled 开关临时停用。

你的接收端应尽快返回 2xx 状态码，耗时的处理请放到后台异步执行。

#查看邮件记录

Messages 标签页按邮件服务器展示邮件记录：

• 顶部统计：Total (24h)、Sent、Pending、Failed。
• 筛选：按状态（Sent、Pending、Soft Fail、Hard Fail、Held）、方向（Outgoing、Incoming）筛选，也可以输入关键字搜索。
• 列表列：ID、Token、From、To、Subject、Status。点击查看详情，可以看到 Message ID、大小、创建时间等信息以及投递记录。
• 操作：状态为 Soft Fail 或 Hard Fail 的邮件可以 Retry 重新发送；状态为 Pending 或 Held 的邮件可以 Cancel 取消。

#常见问题

认证失败：确认用户名是邮件服务器的 Token、密码是 SMTP Credential 类型凭证的密钥，并且凭证属于同一个邮件服务器。

发件人被拒绝：确认 From 地址的域名已在 Domains 中显示 Verified。

发送量较大：订阅详情页顶部的 Send Limit 显示套餐的每小时发送上限。预计会超过这个上限时，请控制发送速率或升级套餐。

#相关文档

• 事务邮件概览
• 发信域名与 DNS 配置