SMTPDog
登录
返回首页

SMTPDog 开发者接入文档

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

Webhook 规范常见问题 FAQ
05 · domains dns

域名验证及 DNS 配置

使用账户生成的 TXT 记录，完成发件域名所有权验证。

1. 添加前确认

添加需要生效套餐和可用节点。max_domains 是当前套餐的硬上限，不是技术上的无限域名。多个域名共享账户当前套餐发送额度。域名名需为 ASCII FQDN；冲突、阈值或节点问题应先排查，不要反复提交。

curl -X POST "${SMTPDOG_API_ORIGIN}/domains" \
  -H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{"domain_name":"example.com"}'

2. 使用真实 TXT 记录

创建响应或 GET /domains/{id} 可返回 dns_records，每项为 type、name、value。DKIM selector、公钥和 SPF include 必须使用实际返回值。这里只解释字段，不提供可发布的演示 TXT。DNS 提供商可能要求相对主机名；已有 SPF 应合并审核，不能盲目覆盖或发布多个 SPF。

字段 / 配置类型 / 状态说明
typestring当前为 TXT
namestring使用返回的完整记录名，核对提供商相对 Host 规则
valuestring使用返回的 DKIM 公钥 / SPF 值，不拼接演示数据
type:  TXT
name:  <use the actual dns_records[].name>
value: <use the actual dns_records[].value>

3. 在 DNS 解析平台添加记录

每个发件域名在你的账户里都有专属的 DKIM 选择器、公钥和 SPF 记录。把它们作为 TXT 记录添加到你的 DNS 解析平台，然后回控制台点击验证。

  1. STEP 01 · 获取专属记录
    在控制台添加发件域名

    在控制台输入要绑定的域名（根域名或子域名），系统会返回专属的 dns_records 列表（包含 type、name、value）。

  2. STEP 02 · 添加 TXT 记录
    在 DNS 服务商处创建

    登录你的域名解析平台，把每条记录添加为 TXT，并注意「主机记录」是否要求只填相对名称。

  3. STEP 03 · 验证
    确认 all_passed

    等待解析生效后回到控制台点击「验证」，当 SPF 与 DKIM 检查项均通过（all_passed 为 true）即可发信。

主流 DNS 解析平台填写教程

不同平台对「主机记录（Host / Name）」是否自动补全主域名后缀的规则不同，请选择你的域名商：

1. 平台进入路径

登录阿里云控制台 → 云解析 DNS →「公网权威解析」→ 找到你的域名 →「解析设置」→「添加记录」。

2. 主机记录（Host / Name）怎么填

重点：「主机记录」只填相对名称，系统会自动补全你的主域名。控制台返回 example.com 时填 @；返回 mail.example.com 时只填 mail；DKIM 只填 <selector>._domainkey。

3. 记录类型与记录值怎么填

「记录类型」选择 TXT，把完整的 SPF 或 DKIM 字符串粘贴到「记录值」。

4. TTL 与生效时间

「解析请求来源」保持默认，TTL 建议选 10 分钟（600 秒），添加后等几分钟再验证。

各服务商控制台的界面会不定期调整。如果菜单名称有出入，请遵循同样的规则：主机记录填相对名称、类型选 TXT、记录值原样粘贴。

主机记录（Host）相对名称转换对照表

当你的平台会自动追加主域名时，请把控制台返回的完整记录名转换为「相对主机记录」：

解析场景控制台返回的 name主机记录填写填写说明
根域名 SPFexample.com@@ 代表根域名；若已有 SPF 请合并，不要新建第二条。
子域名 SPFmail.example.commail去掉末尾的 .example.com，只填子域名前缀。
根域名 DKIM<selector>._domainkey.example.com<selector>._domainkey使用控制台实际返回的 selector，去掉主域名。
子域名 DKIM<selector>._domainkey.mail.example.com<selector>._domainkey.mail保留子域名段 .mail，仅去掉末尾的 .example.com。

常见问题

1. 同一主机名只能有一条 SPF：同一主机名下不能存在多条 v=spf1 记录。若你已为其他邮件服务配置过 SPF，请把控制台提供的 include 合并进原有记录，不要新增第二条。

2. DKIM 值很长：DKIM 公钥超过 255 个字符。多数平台会自动拆分；如果你的平台不会，请在同一条 TXT 记录里拆成多段、每段不超过 255 个字符并各自加引号。

3. 验证接口返回 HTTP 200 只代表检查执行完毕。请确认 all_passed 为 true；未通过时对照 checks[] 里的 expected_value 与 found_values 排查。

4. 主动验证与结果

POST /domains/{id}/verify 不需要正文。HTTP 200 下 all_passed 仍可能为 false。逐项检查 checks 的 passed、expected_value、found_values 与 lookup_error。所有检查通过才作为完成依据；DNS 验证通过不等于节点配置已完成，也不是持续监测承诺。

字段 / 配置类型 / 状态说明
all_passed / statusbool / string全部通过与当前状态
checks[].namestringdkim / spf
record_name / expected_value / passedstring / bool各记录预期值与通过结果
found_values / lookup_errorstring[] / string可省略；用于 DNS 排错
curl -X GET "${SMTPDOG_API_ORIGIN}/domains/${SMTPDOG_DOMAIN_ID}" \
  -H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"

curl -X POST "${SMTPDOG_API_ORIGIN}/domains/${SMTPDOG_DOMAIN_ID}/verify" \
  -H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"

5. 排错与解绑

若 TXT 未匹配，先核对完整 name/value、DNS 生效和提供商主机名格式。没有 DMARC 验证接口。解绑使用 DELETE /domains/{id}，将域名设为 disabled 而保留历史，不保证立即重新绑定或转移到账户。部分创建失败应联系支持，避免无限重试。

继续阅读 — 常见问题