邮件、收件箱和域名的
垃圾邮件检查 API

快速开始

三次调用。无需密钥、账户或注册。 两次请求和一封电子邮件。由于分析需要几秒钟，因此才需要第三次调用。

1. 预留一个地址

   向收件箱端点发送 POST 请求。你会得到一个仅接收一封邮件且在一小时后过期的地址，以及其他所有内容所关联的标识符。

   请求

   # 1. reserve a single-use address
   curl -sX POST 'https://email-spam-tester.com/api/v1/inbox?lang=en'

   响应

   {
     "address": "test-<slug>@t.email-spam-tester.com",
     "slug": "<slug>",
     "expires_at": "2026-01-01T12:00:00Z"
   }

2. 向该地址发送真实邮件

   通过 SMTP，从将要发送营销邮件的平台发送。一半的检查会读取发送平台添加的邮件头，因此手动编写的邮件测量的是错误的对象。

   请求

   # 2. send your message to that address, from your own platform
   To: test-<slug>@t.email-spam-tester.com

3. 轮询状态，然后读取报告

   状态端点返回的数据只有几百字节，并会告诉你是否已经值得获取完整报告。报告本身有数千行。

   请求

   # 3. poll
   curl -s 'https://email-spam-tester.com/api/v1/tests/<slug>/status'

   响应

   {
     "slug": "<slug>",
     "analysis_status": "checks_ready",
     "ai_status": "running",
     "checks_done": 42,
     "checks_total": 42
   }

   请求

   # 4. read the report once analysis_status is checks_ready
   curl -s 'https://email-spam-tester.com/api/v1/tests/<slug>'

   响应

   {
     "report_url": "https://email-spam-tester.com/t/<slug>",
     "score_ours": 86.4,
     "score_compat": 9.2,
     "subscores": {"auth": 100.0, "infra_spam": 78.1, "content": 92.0, "compliance": 75.0},
     "complete": true,
     "checks": [
       {
         "id": "auth.dmarc",
         "status": "warn",
         "title": "DMARC result",
         "summary": "DMARC passes, but the policy is p=none.",
         "weight_ours": -4.0,
         "evidence": {"policy": "none", "aligned": "dkim"},
         "citations": {"standards": [{"title": "RFC 9989 §4.7", "quote": "..."}]}
       }
     ],
     "fixes": [
       {"id": "dmarc-enforce", "gain_ours": 4.0, "gain_compat": 0.0,
        "fix": {"title": "Move DMARC to quarantine", "severity": "medium"}}
     ]
   }

预留一个地址，发送你原本准备发给邮件列表的邮件，然后读取报告。页面显示的所有内容都包含在 JSON 中，包括评分、全部 42 项检查及其证据，以及每项发现所依据的标准章节。

前 100,000 份报告免费，无需密钥，也无需账户。如果你接入的是代理而不是脚本，MCP 服务器比轮询更合适。

端点

基地址为 https://email-spam-tester.com。所有响应均为 JSON。

快速开始

1. 创建测试

   向投递位置端点发出 POST 请求。你会收到一个标记和测试收件箱列表。

   请求

   # 1. create a test
   curl -sX POST 'https://email-spam-tester.com/api/v1/placement' \
     -H 'Content-Type: application/json' \
     -d '{"public_results_accepted":true}'

   响应

   {
     "slug": "<slug>",
     "marker": "est-3f9a1c7e2b4d6a80c5e1f2d3",
     "status": "waiting",
     "deadline": "2026-10-31T12:30:00Z",
     "poll_after_seconds": 60,
     "results": [
       {"address": "<seed>", "provider": "gmail", "kind": "Gmail",
        "placement": "pending", "observed_at": null}
     ],
     "fleet": {
       "status": "observing",
       "results": [
         {"address": "<mailbox>", "provider": "yahoo", "available": true,
          "placement": "pending", "coverage": "pending"}
       ]
     }
   }

2. 向每个收件箱发送一封邮件

   将标记放入主题，并通过你常用的平台一次性发送到所有地址。

   请求

   # 2. one message to every address, with the marker in the subject
   Subject: October invoice est-3f9a1c7e2b4d6a80c5e1f2d3
   To: <seed>, <mailbox>, ...

3. 轮询文件夹

   每个地址都会填入其提供商和文件夹。轮询直到状态不再是 waiting。

   请求

   # 3. poll for the folders
   curl -s 'https://email-spam-tester.com/api/v1/placement/<slug>'

   响应

   {
     "status": "complete",
     "received": 2,
     "total": 2,
     "results": [
       {"address": "<seed>", "provider": "gmail", "kind": "Gmail",
        "placement": "primary", "observed_at": "2026-10-31T12:04:11Z"},
       {"address": "<seed>", "provider": "gmail", "kind": "Google Workspace",
        "placement": "promotions", "observed_at": "2026-10-31T12:04:11Z"}
     ],
     "fleet": {
       "status": "finished",
       "results": [
         {"address": "<mailbox>", "provider": "yahoo", "available": true,
          "placement": "inbox", "coverage": "ok"},
         {"address": "<mailbox>", "provider": "outlook", "available": true,
          "placement": "spam", "coverage": "ok"}
       ]
     }
   }

端点

快速开始

1. 发起一次 GET 请求

   传入域名。ip 添加你的发件地址，selector 指定要读取的 DKIM 选择器。

   请求

   curl -s 'https://email-spam-tester.com/api/v1/infra/check?domain=example.com&selector=mail&diff=true'

2. 读取判定结果

   ok 是供脚本使用的结果，sections 显示哪个部分失败。

   响应

   {
     "id": "ir_01JB8Y4T2M6K9QZ7H3V5N1XWDA",
     "domain": "example.com",
     "checked_at": "2026-10-31T12:00:00Z",
     "ok": false,
     "status": "fail",
     "score": 78,
     "coverage": {"answered": 7, "total": 8},
     "ips": [{"ip": "203.0.113.5", "sources": ["mx", "spf"], "managed": false}],
     "sections": {
       "dkim": {"status": "pass", "core": true, "findings": [], "data": {}},
       "ptr": {"status": "fail", "core": true, "findings": [], "data": {}}
     },
     "not_checked": [
       {"check": "dkim_signature", "reason": "needs_a_message"},
       {"check": "alignment", "reason": "needs_a_message"}
     ],
     "diff": {
       "baseline": {"id": "ir_01JB2...", "checked_at": "2026-10-24T12:00:00Z"},
       "first_run": false,
       "changed": true,
       "worsened": true,
       "status_from": "pass",
       "score_from": 100,
       "changes": [
         {"path": "dkim.key.mail.sha256", "section": "dkim", "kind": "removed",
          "severity": "critical", "effect": "worsened", "from": "9f2c...", "to": null}
       ],
       "not_compared": [
         {"path": "blocklist_ip.203.0.113.5.bl.spamcop.net.listed", "reason": "lookup_failed"}
       ]
     }
   }

3. 将它加入 cron

   使用 diff=true 时，每次运行都会与你的上一次运行进行比较，jq 会将结果转换为退出码。

   请求

   # exits non-zero if the domain is broken or its setup changed
   curl -s 'https://email-spam-tester.com/api/v1/infra/check?domain=example.com&selector=mail&diff=true' \
     | jq -e '.ok and (.diff.changed | not)'

读取响应

完成的检查会返回 200，判定结果位于正文中。status 是必需部分中的最差状态：spf、dkim、dmarc、ptr、blocklist_ip、blocklist_domain、mx 和 smtp。必需部分中的 unknown 计为 warn。当 status 为 pass 或 warn 时，ok 为 true。score 根据已返回结果的必需部分计算，范围为 0 到 100；当 error 和 unknown 导致有结果的适用权重不足一半时，score 为 null。mta_sts、tls_rpt、bimi、dnssec、dane、ns 和 registration 会被报告和比较，但不影响 ok 或 score。

一个部分可以是 pass、warn、fail、error（我们无法检查）、unknown（信息不足）或 skipped（不适用）。skipped 不影响结果，原因位于 not_checked 中。dkim_signature 和 alignment 始终存在，因为它们需要真实邮件。

ip 和 selector 会改变什么

PTR 和黑名单与地址有关，因此一次运行需要一些地址。它使用你传入的 ip 值。如果没有传入，则从你的 MX 主机以及根 SPF 记录中仅包含单个地址的 ip4: 和 ip6: 项中最多获取四个地址。已知邮件提供商的地址会被列为 managed 并不进行检查，如果没有剩余地址，ptr 和 blocklist_ip 会返回 skipped。无法从 DNS 读取 selector，因此一次运行会尝试你提供的 selector、你之前的运行找到的 selector，以及常用名称列表。什么也找不到并不能证明什么，dkim 会返回 unknown。如果你从自己的服务器发送邮件，请同时传入这两项。

更改了什么

diff.changes 中的每个条目都有一个 path、一个 kind（added、removed、changed）、一个 severity（critical、warning、info）和一个 effect（worsened、improved、neutral）。只有 critical 和 warning 会设置 diff.changed，因此轮换为相同长度的 DKIM 密钥、新增 MX 地址或续期证书不会导致 cron 行失败。diff.worsened 取决于任一变更的 effect。首次运行时没有可供比较的内容，diff.first_run 会对此进行说明。

基线始终是你自己的某次运行，因此其他人在你的两次运行之间检查该域名不会隐藏任何内容。本次无法读取的任何内容都会进入 diff.not_compared，并保留其上次已知值，这意味着在中断期间发生的更改会在查询恢复正常后显示。使用不同 ip 或 selector 的运行仍属于同一序列，而该运行未请求检查的内容也不会进行比较。

为什么定时检查应使用密钥

如果没有密钥，你的历史记录归属于你 IP 地址的带密钥哈希，因此地址更改后历史记录就会中断，而且同一地址后的用户会共享历史记录：同事的运行会移动你的基线。在 Authorization: Bearer 中使用个人 API 密钥后，历史记录会跟随该密钥。带密钥的运行会保留 365 天，并且只能使用该密钥打开。不带密钥的运行会保留 30 天，任何拥有其 id 的人都可以打开。

每个 IP 每分钟 6 个请求、每天 50 个请求，或每个密钥每分钟 30 个请求、每天 500 个请求。超过限制时，响应为 429，并包含 Retry-After。60 秒内的相同请求会来自缓存，标记为 cached: true，不写入运行记录，也不计入限制。读取已存储的运行时，每个客户端每分钟允许 120 个请求。包含 Retry-After 的 503 表示正在运行的检查过多，或者在读取已存储的运行时表示存储不可用。401 表示密钥错误。422 包含 detail.code：invalid_domain、invalid_ip、invalid_selector、invalid_check、invalid_since、unknown_baseline 或 account_required。

端点

快速开始

1. 选择检查项

   从下面的列表中选择工具，并传入其要求的域名、地址或 IP。

   请求

   curl -s 'https://email-spam-tester.com/api/v1/tools/spf?domain=example.com'

2. 查看状态和检查结果

   每个工具都会返回状态及其检查结果。后续字段取决于具体工具。

   响应

   {
     "tool": "spf",
     "query": {"domain": "example.com"},
     "checked_at": "2026-10-31T12:00:00Z",
     "duration_ms": 412,
     "status": "fail",
     "findings": [
       {"code": "spf.too_many_lookups", "level": "fail",
        "params": {"limit": 10, "count": 12},
        "message": "RFC 7208 §4.6.4 allows at most 10 DNS lookups, and this record needs 12, so receivers return permerror."}
     ],
     "record": "v=spf1 include:_spf.example.net ~all",
     "lookups": {"count": 12, "limit": 10, "void": 0}
   }

端点