在 Abnormal 上开发。

API 能做什么

API 管理一个工作区的邮件服务。它能做的事，管理员在管理控制台里也都能做；有了 API，就可以交给脚本、集成或 Agent 去做。

• 域名：验证所有权、接入域名、检查 DNS、设置 catch-all、添加别名域名。
• 邮箱：创建、删除和恢复邮箱，修改密码、状态、容量、备注和每日发信上限。
• 地址：转发规则、普通别名和邮件列表。
• 合规与报表：法律保留、不活跃邮箱、各域名的存储用量和发信最多的邮箱。
• 事件：邮箱、域名、订单、批量任务和安全事件的签名 Webhook。
• 收发邮件：用你的域名发信、跟踪每封邮件的投递，并以 Webhook 接收邮件（需开通）。
• Agent 邮箱：一次调用为 AI Agent 建好邮箱，读收件箱、按会话回复，并发一把只能用于这个邮箱的密钥。
• 邮件应用：让邮箱用户通过 OAuth 授权你的应用读取他们的邮件、以他们的身份发信。
• 投递：抑制列表、邮件追踪，以及替你读回的延迟退信和垃圾邮件投诉。
• 客户端与连接器：TypeScript 和 Python SDK、命令行工具、n8n 和 Zapier，以及飞书、钉钉群机器人（见下方应用目录）。
• 批量：把多项修改放进一个按顺序执行、可安全重试的请求。

申请工作区和密钥

1. 申请工作区。 API 属于管理控制台里的一个工作区。申请工作区后会有人工审核，通过后你会作为管理员收到邀请。如果申请页提供“开发者工作区”，选它即可在确认邮箱后立即获得一个，用测试密钥试用 API。
2. 创建密钥。 在管理控制台打开 设置 → API 密钥，创建一个密钥，只勾选代码需要的权限范围。只有管理员能创建密钥。
3. 立即保存。 完整的密钥只在创建时显示一次。把它放在密钥管理工具或环境变量里，不要写进代码仓库、网址或日志。

密钥能做的事永远不会超过其所有者当前在控制台里的角色；吊销后，下一次请求就会被拒绝。工作区的每位管理员都能看到并吊销其他账号的密钥。

第一个请求

所有请求都发往 https://console.abnormalhq.com/api/v1，并以 Bearer 令牌的形式带上密钥。建议第一次先调用 GET /capabilities：它会返回可用的权限范围、功能和当前生效的限制。

API_BASE='https://console.abnormalhq.com/api/v1'
printf 'API key: '; stty -echo; IFS= read -r API_KEY; stty echo; printf '\n'

curl --fail-with-body "$API_BASE/capabilities" \
  -H "Authorization: Bearer $API_KEY"

用隐藏输入读入密钥，它就不会留在 shell 历史里。用完后运行 unset API_KEY。

权限范围

每个操作需要一个权限范围，在下方的接口列表里标在操作旁边。写权限不包含对应的读权限。有两个例外：POST /batch 会逐一检查其中每项操作的权限范围，GET /batch/{requestId} 只接受提交该批次的那个密钥。

• domains:read、domains:write：域名、接入申请、DNS 与连接状态、catch-all、别名域名。
• mailboxes:read、mailboxes:write：邮箱、回收站、发信上限和用量报表。
• forwarders:*、aliases:*、lists:*：转发规则、普通别名和邮件列表。
• holds:*、webhooks:*、suppressions:*、trace:read：法律保留、Webhook、抑制列表和邮件追踪。
• agent_tasks:*：跟进任务，即以某个邮箱身份回复邮件的 Agent。
• emails:*、inbound:*：API 发信与收信路由（需手动勾选，新密钥默认不含）。
• agent_mailboxes:*、mail_apps:*：Agent 邮箱，以及邮箱用户可以授权的应用（同样需手动勾选）。

域名、转发、别名、邮件列表、法律保留和 Webhook 即使只读也需要管理员角色；邮箱和跟进任务的权限范围运营人员也能用，其中的读权限查看者也能用。

请求、响应与错误

• 请求体是 JSON（Content-Type: application/json），最大 16 KiB。
• 成功结果是 { "data": … }，列表另带 pagination。创建成功返回 201。
• 路径里的 {id} 是 API 返回的记录 ID，不是邮箱地址或域名。
• POST /batch 按顺序执行 1 到 25 个操作，并且必须带 Idempotency-Key：用同一个键重发同一批操作，会直接返回保存的结果，不会执行两次。

所有错误的格式都一样。请根据 code 判断，不要根据 message：后者是写给人看的，内容可能会变。

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again in 42 seconds.",
    "details": { "retryAfter": 42, "limit": 300 }
  }
}

遇到超时、连接中断或 502 后，先读取当前状态，再决定是否重做写操作。返回 409 且错误码为 provisioning_uncertain 时，邮箱可能已经创建也可能没有：请用 details.mailboxId 查询，不要再创建一次。

频率限制

• 按密钥计数，REST 和 MCP 合并计算。默认每分钟 300 次；当前生效的限制由 GET /capabilities 的 limits.requestsPerMinute 给出。
• 每个响应都带 RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset 和 RateLimit-Policy。
• 超出限制时返回 429，并用 Retry-After 给出需要等待的秒数。被拒绝的请求什么都没做，等待之后重发是安全的。
• 同一地址发来太多无效密钥，该地址会被暂时封禁，有效密钥也会被拒绝。请修好发错密钥的客户端。

Webhook

Webhook 是一个 https 地址，工作区里发生事情时会向它发送 POST 请求，你就不用轮询。用 POST /webhooks 创建；签名密钥（whsec_…）只在这次响应里出现一次。每个工作区最多 10 个。

每次投递都在 X-Mailhq-Signature 头里签名，格式为 t=<milliseconds>,v1=<hex HMAC-SHA256>（毫秒时间戳和十六进制的 HMAC-SHA256），签名内容是时间戳、一个点和原始请求体。先校验签名，再信任请求体：

import { createHmac, timingSafeEqual } from "node:crypto";

/** rawBody: the body exactly as received; header: the X-Mailhq-Signature value. */
export function verifyMailhqWebhook(secret, rawBody, header, toleranceMs = 5 * 60_000) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "");
  if (!match) return false;
  const timestamp = Number(match[1]);
  if (Math.abs(Date.now() - timestamp) > toleranceMs) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
  const given = Buffer.from(match[2], "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

• 在 10 秒内返回 2xx，之后再处理业务。
• 投递至少一次且不保证顺序：用事件的 id 去重。
• 投递失败会以逐渐拉长的间隔重试约 17 小时。连续失败 3 天的 Webhook 会被停用，直到你重新启用。
• POST /webhooks/{id}/test 会发送一个测试事件，用来检查接收端。设置 → 开发者 会列出所有 Webhook 最近的投递及接收方的回应，并可重新投递；状态页会显示 Webhook 投递是否准时。
• 想不写接收端就在群聊里收到事件，创建 Webhook 时设 "format": "feishu" 或 "dingtalk"，填写群机器人的地址（签名密钥填在 botSecret）：每个事件会以一条简短消息到达。

收发邮件

用你自己的域名、通过域名自己的邮件服务器发信，跟踪每封邮件的投递结果，并把指定邮箱收到的邮件推送到 Webhook。发信功能默认关闭，需由我们为你的工作区开通并设定每日上限，请来信申请。测试密钥可以直接向沙箱发信。

• PUT /domains/{id}/sending 为域名创建发信账号：邮件以该域名的 DKIM 密钥签名发出，退信回到这个账号，From 可以是该域名下的任意地址。
• POST /emails 发送一封邮件（POST /emails/batch 一次最多 50 封）；带上 Idempotency-Key 即可安全重试。抑制列表中的收件人会被跳过。
• GET /emails/{id} 给出每个收件人的结果：已发出、已送达、投递延迟或退信。同样的变化也会以 email.sent、email.delivered、email.delivery_delayed、email.bounced 和 email.failed 事件推送。
• PUT /mailboxes/{id}/inbound 开启收信路由：邮箱收到的每封邮件都会以 message.received 推送，附带纯文本正文；完整邮件和附件用 GET /mailboxes/{id}/messages/{emailId} 读取。用别名或 catch-all 可以把多个地址汇入同一个路由邮箱。
• 如果你的套餐按发信量计费，需先在 设置 → 开发者 → 计费 中订阅，否则正式密钥发信会得到 402 billing_required。每封交给邮件服务器的邮件计一次，与收件人数量无关。
• 管理后台的 设置 → 开发者 会显示当天的发信额度、最近的 API 调用及其错误码、每封发出的邮件和每个收件人的结果。
• 回到域名发信账号的延迟退信和垃圾邮件投诉（反馈环报告）会被读回：收件人变为 bounced，或得到 complainedAt 和一个 email.complained 事件，并被加入抑制列表。
• 新开通的工作区会先预热：第一天最多 50 封，此后每天翻倍，直到上限。退信或投诉过多时正式发信会自动暂停（403 email_api_paused，并推送 email.sending_paused 事件），直到我们核查。
• 只能走 SMTP 的软件可以用 POST /domains/{id}/smtp-credentials 经域名自己的服务器发信：这个密码只能登录和发信，与 API 密钥分开创建和撤销。这样发出的邮件不是 API 邮件：没有 GET /emails 记录，也没有投递事件，计入的是发信账户在服务器上自己的每日限额，而不是工作区的发信额度。

Agent 邮箱

Agent 邮箱是你域名下一个真正的邮箱，一次调用就为 AI Agent 建好，收信路由和发信都已开启。

• POST /agent-mailboxes 传入 domain 和 name 即可创建；GET /agent-mailboxes/{id}/messages 读取收件箱，POST …/send 发送新邮件，POST …/messages/{emailId}/reply 在原会话中回复。
• POST /agent-mailboxes/{id}/keys 返回一把只对这个邮箱有效的密钥：交给 Agent，它就碰不到工作区里的其他任何东西。
• Agent 收到的邮件同时以 message.received 事件推送，无需轮询。PATCH 和 DELETE …/messages/{emailId} 可把邮件标为已读或删除，GET …/attachments/{index} 可下载附件。

由邮箱用户授权的应用

你的应用可以在邮箱用户同意后读取其邮件、以其身份发信，全程看不到用户的密码：在 Abnormal 网页邮箱上使用 OAuth 2.0 授权码流程加 PKCE。

• 用 POST /mail-apps 注册应用：名称、回调地址，以及它可以申请的权限 mail.read、mail.send 和 mail.modify。所有应用都是公开客户端：没有 client secret，必须使用 PKCE（S256）。
• 把用户引导到网页邮箱的 /oauth/authorize；用户登录后会看到你的应用名称和申请的权限，确认即可。在 /api/oauth/token 用授权码换取访问令牌（1 小时）和每次使用都会轮换的刷新令牌。
• 带着令牌调用 Mail API：GET /api/mail/v1/messages 和 /messages/{id} 读取、搜索邮件（…/attachments/{index} 下载附件），POST /api/mail/v1/send 以该邮箱发信，可带附件并在“已发送”中留存副本；有 mail.modify 时应用还能标记、移动和删除邮件。
• 用户随时可以在网页邮箱设置里撤销授权，修改邮箱密码也会终止全部授权；DELETE /mail-apps/{id} 会一次终止你的应用的全部授权。

给 AI Agent 用的 MCP

同样的操作也作为工具提供在 MCP 服务器 https://console.abnormalhq.com/api/mcp 上（Streamable HTTP），密钥、权限范围和频率限制都相同。只给 Agent 它需要的权限范围。以 Claude Code 为例：

claude mcp add --transport http abnormal https://console.abnormalhq.com/api/mcp \
  --header "Authorization: Bearer $ABNORMAL_API_KEY"

支持 OAuth 登录的客户端（例如 claude.ai、Claude Desktop 和 Claude Code 上的 Claude）只需要这个地址：它们会自行注册，由管理员在授权页上批准权限，令牌会自动续期。不加请求头，客户端就会打开登录页。

应用目录

除了自己调用 API，把其他软件接入 Abnormal 的所有方式。管理控制台的 设置 → 开发者 → 集成 也列出了同样的内容。

• Claude 及其他 MCP 客户端（可用）：上文的 MCP 服务器，支持 OAuth 登录。
• 你自己的应用，面向你的邮箱用户（可用）：使用 OAuth 的邮件应用，见上文。
• 飞书和钉钉（可用）：把 Webhook 事件或你的控制台通知推送到群机器人。
• Slack 和 Telegram（可用）：把你的控制台通知发到频道或会话。
• TypeScript SDK、Python SDK 和 `abnormal` 命令行工具（尚未发布）：带类型的调用、重试、幂等键和 Webhook 校验；命令行工具将可用 brew install abnormalhq/tap/abnormal 安装。
• n8n 和 Zapier（尚未发布）：n8n 的节点和触发器，以及 Zapier 的触发器、动作和搜索。

版本与变更

• 版本写在路径里：/api/v1。在同一版本内只做新增：新接口、新的可选字段、新的响应字段、新的枚举值和新的事件类型。你的代码应当能接受不认识的字段和值。
• 在 v1 里删除或修改任何东西都会先公告，在规范里标为弃用，并在每个响应里带上 Deprecation 和 Sunset 头：代码会发送的内容至少提前 6 个月，只会读取的字段或值至少提前 3 个月。
• 下方接口列表所依据的 OpenAPI 3.1 规范可以下载 JSON 文件，供代码生成器和 API 工具使用。
• 服务状态页会显示管理 API 近 30 天的可用率（每分钟检测一次），以及故障和维护。你自己的监控可以轮询 GET https://console.abnormalhq.com/api/health，无需密钥。

测试模式

创建密钥时打开 测试密钥，就可以在不动到正式域名和邮箱的情况下开发集成。它的令牌以 mhq_test_ 开头，所有调用都发生在本工作区的沙箱里；沙箱的邮件服务器是模拟的，不会投递任何邮件，也不会查询 DNS。

• 域名必须以工作区的专属区域 <slug>.test 结尾（例如 shop.acme.test），GET /capabilities 会在 sandbox.domainZone 里给出它。所有权验证无需 DNS 即可通过。
• 邮箱、别名、邮件列表、转发、法律保留、批量操作和抑制列表都和正式工作区一样可用，Webhook 也会真实投递。
• 发信无需开通：除本地部分以 bounce 开头的地址会退信外，所有收件人都会立即“送达”；发到开启收信路由的沙箱邮箱的邮件会以 message.received 推送。
• 邮件追踪、跟进任务、传输安全、读取收到的邮件（包括 Agent 邮箱的）和邮件应用需要真实的邮件，测试密钥调用它们会得到 403 test_mode_unsupported。
• 每个沙箱最多 5 个域名、100 个邮箱。

暂不提供

• 未经邮箱用户授权读取未开启路由的邮箱。
• 打开与点击跟踪：这是有意不做的，它会读取人们怎么处理自己的邮件，我们的网页邮箱也不这样做。
• SDK 包、命令行工具以及 n8n、Zapier 的上架已经做好但尚未发布：发布后本页会给出链接。

邮箱仍然通过网页邮箱、IMAP 和 SMTP 收发自己的邮件。关于 API 的问题请发邮件到 support@abnormalhq.com。

错误码

每个错误都有一个稳定的 code。下表列出全部错误码，以及对应的状态码、含义、处理办法和能否原样重试。v1 内可能新增错误码，遇到不认识的请按 HTTP 状态码处理。说明为英文。

• 不能：请求不改就会一直以同样方式失败。
• 稍后：什么都没发生，等一会儿可能成功。有 Retry-After 时按它等待。
• 先核对：结果未知或状态已变。先读取当前状态再决定，盲目重发可能把事情做两遍。

接口列表

v1 的全部操作，按功能分组，并标出所需的权限范围。路径相对于 API 地址；请求和响应的结构见规范。接口说明为英文。