Mailzero 文档

列出常设委托

所有者的常设委托规则，按顺序：名称、匹配谓词、受托人(智能体身份或工作空间成员)、自主权级别、每个匹配的次数。需要 assistant:read；智能体令牌被拒绝。

创建常设委托

将某类事项一次性移交给智能体或人员。match 是显式谓词，绝不是模型调用：senderAddress、senderDomain、organisation、workKeyPrefix、senderKind、mailboxIds、labels、subjectPattern(锚定、不区分大小写)、minOccurrences、minConfidence（校准分类器对 category: 标签给出的概率，0.5 到 1） 中的任意一个；每个声明的条件都必须满足。规则是有序的，第一个匹配的规则获胜；除非另有说明，级别为 observe。匹配的规则将下一个匹配的事项移交给受托人，通过委托通知告知，Today 显示原因。需要 assistant:write；智能体令牌被拒绝。

更改常设委托

重命名、启用或禁用、重新排序、更改匹配条件、受托人、级别或授权。将级别降低到 observe 是规则的一键终止开关。需要 assistant:write；智能体令牌被拒绝。

删除常设委托

移除规则；它移交的事项返回给所有者，受托人所做操作的记录保留。需要 assistant:write；智能体令牌被拒绝。

在样本事实上尝试常设委托

模拟运行：哪条规则会处理具有这些事实（邮箱、键、发件人、主题、标签、出现次数）的事项，以及原因。不会更改任何内容。需要 assistant:write；智能体令牌会被拒绝。

针对常设委托的级别和授权尝试一个效果

今天在规则下请求的效果的验证顺序的模拟运行：级别允许该类型；授权允许收件人、数量（今天已执行的效果计数）、时间表、从事项读取的支出、风险类别；必需的审批人已批准。回答计划将采取的状态（proposed、approved、escalated 或 rejected）以及每项检查和原因。不会更改任何内容。需要 assistant:write；智能体令牌被拒绝。

读取任务指标

滚动窗口期内（默认三十天，window_days 从 1 到 90）任务层的七个数字，针对账户和每个常设委托：未经所有者关闭的事项、从到达到完成的时间、按提议执行的计划、已编辑和已拒绝的计划、每个事项的升级次数、执行后的更正次数、冲突次数、每个事项的模型成本。从收据、计划、升级和账本中读取；没有估算值。需要 assistant:read。

获取审批队列

等待所有者处理的计划(在草稿阶段提出的,或被授权持有的)以及受托人提出的问题,涵盖读者可以看到的事项。通过工作项的交互来回应:批准或拒绝计划,选择选项或对问题给出指示。需要 assistant:read。在身份验证邮件被排除在助手之外之前由此类邮件生成的事项，对于没有 email:auth_secrets 的读者，会隐藏其标题、摘要、请求和计划效果后再显示。

获取委派建议

助手提议的常设委派：某事项在九十天内至少重复出现三次（相同组织或发件人）且每次处理方式相同（ignored、answered、closed、handed to one agent），并预填充规则。默认显示未处理的建议。在所有者接受之前不会创建任何内容。需要 assistant:read；智能体令牌会被拒绝。

接受或拒绝委派建议

接受：建议关闭，预填充的规则返回供客户端创建（POST /api/assistant/rules）。拒绝：建议关闭且相同事项和处理方式不会再次出现。需要 assistant:write；智能体令牌会被拒绝。

列出附加到受让人的授权

附加到所有者的智能体和成员的授权，在每个将事项交给他们的规则之上；规则和受让人中更严格的适用。需要 assistant:read；智能体令牌被拒绝。

设置受让人的授权

将授权附加到智能体身份或工作区成员；它们替换受让人之前的授权并限制每个将事项交给他们的规则。需要 assistant:write；智能体令牌被拒绝。

移除受让人的授权

受让人仅保留每个规则授予的内容。需要 assistant:write；智能体令牌被拒绝。

读取任务信封

移交的事项，按受托人所需：带证据的摘要、事实、委托（受托人、规则、级别、允许的效果类型、有效授权）、开放和最近的计划、租约。智能体令牌读取移交给它的事项以及它操作的邮箱的事项；所有者读取自己的事项。需要 assistant:read。在身份验证邮件被排除在助手之外之前由此类邮件生成的事项，对于没有 email:auth_secrets 的读者，会隐藏其标题、摘要、请求和计划效果后再显示。

获取或续订任务租约

两个受托人永远不会处理同一事项：租约指定谁处理它直到何时（默认十五分钟，最多一小时）。再次获取会续订租约；在到期前，另一个持有者会被拒绝并返回 TASK_LEASED。效果请求会自动获取租约。需要 assistant:write。

归还租约

释放调用者持有的租约；另一个受托人持有的租约不受影响。需要 assistant:write。

请求对任务执行效果

受托人请求一个或多个效果（回复、转发、标签、延后、解决、备注、请求）。委托的级别决定允许的类型，授权限制它们：在 guarded_send 或 operate 的授权范围内（以及 triage 的入站类型），效果立即执行并返回回执；在 draft 级别，它们等待所有者批准；授权失败会升级到所有者；级别不允许的类型会被拒绝。所有者自己的请求立即执行。相同的幂等键会再次返回第一个计划。需要 assistant:write。

停下来并询问所有者

受理人提出问题并附上证据,必要时还包括其看到的选项。所有者通过对此创建的决策进行普通的选择或指示交互来回答;事项在 Today 中显示为需要所有者,租约被释放,任务等待。需要 assistant:write。

报告任务

受理人做了什么以及如何结束:完成(事项解决,或在仍期待答案时等待)、受阻(询问所有者)或交还(所有者接管且规则在此事项上保持关闭)。声明与平台写入的收据进行核对:没有收据的声明记录为声明,绝不记录为事实。租约被释放。需要 assistant:write。

读取智能体对一条消息确立的内容

对此消息的分析产生的知识:声明(主体、谓词、带类型和货币的值、依据、置信度、有效性、证据)、实体、承诺和期望。过程中不进行任何计算:管道从未分析过的消息会返回 analysed: false 并附带 reason(当邮箱不在智能体中时为 not_enabled,当分析尚未发生时为 not_analysed)。需要 assistant:read。

使用您自己的模式从消息中提取所需字段

对消息文本(主题、发件人、正文)进行一次模型调用,使用调用方的 JSON 模式(对象和基本类型,最多 8 KB,无引用):返回该形状的 data、confidence(0 到 1)和 evidence_quotes(逐字摘录)。按(消息、模式、指令)缓存,因此相同问题只需一次调用(之后 cached: true)。受账户的模型预算限制(用尽时返回 429,模型路由关闭时返回 503)。登录验证码邮件返回 403 AUTH_MESSAGE。正文超过 60,000 字符返回 413。

获取 Mailzero 助手设置

返回助手的启用状态、shadow/pause 标志、同意版本、隐私路由、邮箱范围以及您拥有的所有邮箱。需要 assistant:read 授权。

{
  "enabled": false,
  "shadow_enabled": true,
  "paused": false,
  "mailbox_ids": [
    "mbx_123"
  ],
  "history_window_days": 30,
  "privacy_route": "private_cloud",
  "attachment_vision": false,
  "pipeline_version": "communication-analysis.v1",
  "consent": {
    "required_version": "mailzero-personal-ai.v1",
    "accepted_version": "mailzero-personal-ai.v1",
    "accepted_at": "2026-09-02T09:12:00.000Z"
  },
  "mailboxes": [
    {
      "id": "mbx_123",
      "slug": "hello",
      "domain": "example.com",
      "name": "Hello",
      "kind": "api",
      "address": "hello@example.com"
    }
  ]
}

更新 Mailzero 助手设置

显式启用、暂停、恢复或限定助手处理范围。发送 mailbox_ids: [] 会禁用所有邮箱并取消正在运行的历史记录导入。恢复需要当前的同意版本。邮件接收保持独立。需要 assistant:write 授权。

{
  "ok": true,
  "enabled": true,
  "shadow_enabled": true,
  "paused": false,
  "mailbox_ids": [
    "mbx_123"
  ]
}

同意并启动后台历史记录导入

记录当前明确的AI同意，在选定的用户拥有的邮箱上启用影子处理，并创建可恢复的近期历史记录后台导入。客户端可以立即关闭并轮询GET /api/assistant/backfill。需要assistant:write授权。

{
  "ok": true,
  "preview": {
    "mailbox_ids": [
      "mbx_123"
    ],
    "history_window_days": 30,
    "scanned": 0,
    "enqueued": 0,
    "capped": false,
    "background": true,
    "backfill_id": "bf_456"
  }
}

获取后台历史记录导入进度

返回扫描/分析阶段、已处理和总消息数、百分比、自适应预计完成时间、暂停状态以及应用是否可以关闭。需要assistant:read授权。

{
  "backfill": {
    "id": "bf_456",
    "status": "processing",
    "phase": "analysis",
    "paused": false,
    "processed": 12,
    "total": 40,
    "failed": 0,
    "percent": 30,
    "estimated_seconds_remaining": 240,
    "estimated_completion_at": "2026-09-02T09:20:00.000Z",
    "can_close_app": true,
    "started_at": "2026-09-02T09:12:00.000Z",
    "completed_at": null
  }
}

重试失败的历史记录导入消息

为仍启用AI的邮箱重新排队最新导入中的终端失败。消息出现在此之前，自动重试已经用尽。需要assistant:write授权。

{
  "ok": true,
  "retried": 2
}

获取基于事实的Today决策队列

返回带有 as_of、lag、coverage 和 warnings 的版本化 Now、Needs you、Waiting、Upcoming 和最近 Handled 投影。每个项目链接到其源消息；此处不会发送邮件。需要 assistant:read 授权。身份验证邮件（登录验证码、密码重置、魔术链接）永远不会成为事项，也永远不会到达模型。在身份验证邮件被排除在助手之外之前由此类邮件生成的事项，对于没有 email:auth_secrets 的读者，会隐藏其标题、摘要、请求和计划效果后再显示。

{
  "type": "today",
  "as_of": "2026-09-02T09:15:00.000Z",
  "projection_lag_ms": 4200,
  "category": null,
  "categories": {
    "partner_inquiry": 1
  },
  "tag": null,
  "tags": {
    "lumenworks": 1
  },
  "sections": {
    "now": [
      {
        "id": "wi_789",
        "version": 3,
        "status": "needs_judgment",
        "title": "Investor update",
        "summary": "Paul needs the August metrics before his 16:00 partner call.",
        "category": "partner_inquiry",
        "tags": [
          "lumenworks"
        ],
        "proposed_tags": [],
        "mailbox": {
          "id": "mbx_123",
          "address": "hello@example.com",
          "name": "Hello"
        },
        "source": {
          "type": "domani-postgres",
          "conversation_id": "conv_1",
          "event_id": "msg_1",
          "revision": 1
        },
        "attention": {
          "level": "now",
          "reason": "Deadline today from a known investor",
          "confidence": "high",
          "deadline": "2026-09-02T16:00:00.000Z"
        },
        "decision": {
          "id": "dec_1",
          "version": 1,
          "status": "open",
          "question": "How do you want to answer Paul?",
          "options": [
            {
              "id": "opt_send",
              "label": "Send current metrics",
              "recommended": true
            },
            {
              "id": "opt_tomorrow",
              "label": "Ask for tomorrow"
            }
          ]
        }
      }
    ],
    "needs_you": [],
    "waiting": [],
    "upcoming": [],
    "handled": []
  }
}

获取一个助手 Work 项目和确切的当前计划

返回已落实的 Work 项目、其未决 Decision 和选项、确切的当前 Action 计划、未完成的承诺和期望、交互和回执。需要 assistant:read 授权。在身份验证邮件被排除在助手之外之前由此类邮件生成的事项，对于没有 email:auth_secrets 的读者，会隐藏其标题、摘要、请求和计划效果后再显示。

读取一个工作项的情况简报

智能体在行动前阅读的一份文档：情况（状态、注意事项、重复性、发件人）、迄今为止的故事（其中的每封邮件，无论是否已分析）、分析确立的事实（包含价值、依据和有效性的声明，以及实体）、未完成的承诺和期望（等待谁处理以及自何时起）、已解决的事项（已关闭的循环和回执）、当前的决策及其选项、建议的下一步（当存在决策的推荐选项时采用该选项，否则采用规则：逾期的承诺、需要追踪的逾期期望、需要回答的发件人请求）以及证据消息。确定性且成本低：无需模型调用。智能体令牌读取其操作的邮箱项目以及交给它们的项目。

读取某个通信者的情况简报

在回复某人之前需要了解的内容：他们在你可以读取的邮箱（或一个邮箱）中最近活跃的工作项的简报、他们落后的其他项目，以及他们最近的十封邮件。当尚未分析到来自他们的任何内容时，brief 为 null。

读取 Work 项目背后的事实

从该项目的每次分析中合并的声明和实体(最新的优先),加上其存储的承诺和期望及其状态。智能体令牌可读取其操作的邮箱的项目以及交给它们的项目。

将 Work 事项标记为已打开

记录所有者已在当前版本打开此 Work 事项，并清除其未读标记，直到该事项再次变更。需要 assistant:write 范围。

助手了解到的关于您的信息

同一发件人或组织每次回来都被忽略后助手建议的静音规则、生效中的静音（助手排除在“今天”之外的发件人、域名或情形）及各自的原因，以及确认过一次的标签（每个都会自动应用于同一项目的下一个事项）。通过 suggestions 端点接受静音规则；用 mutes 端点遗忘静音，用 tags 端点遗忘标签。

删除静音

该发件人、域名或情况的下一封邮件将再次成为事项。

遗忘一个标签

不再自动应用任何内容：该项目的下一个事项会再次建议该标签。带有它的事项保留它。

调查事项:注册局和链接的信息

在那一刻读取公共基础设施关于发件人域名的事实（其注册日期和注册商、其SPF和DMARC态势、是否接收邮件）、源消息中每个链接的真实去向（逐跳跟踪的重定向、最终主机及其域名的事实），以及每个附件的真实内容（其前几个字节与名称和声明的类型进行对比）。用这些事实添加的信号回答档案（几天前注册的域名、落地到其他地方的链接、不保护任何内容的发件人域名、被命名为文档的程序）。无供应商、无账户、不存储任何内容；查找失败本身就是一个事实。

事项背后是谁：组织、相关人员、历史

返回事项的发件人卡片：已存储域名档案所知的发件人组织（名称、法定名称、类别、网站、注册日期、邮件态势；共享邮件域名如 gmail.com 或从未分析过的域名为 null，且从不进行实时分析）、故事消息在 from、to 和 cc 中携带的人员及其角色和是否属于同一组织（读者自己的邮箱除外），以及关系：读者所有邮箱中从该地址收到了多少邮件（最多计数到 50）、首次和最近的时间、发件人的其他事项以及同一域名同事提出的事项。需要 assistant:read scope。

记录一个受限的人工 Decision

选择一个选项、给出指令、接管、暂停、忽略、更正、报告信任判定（钓鱼或合法），或批准或拒绝等待中的计划（已批准的计划立即执行，其收据在响应中）。调用由 work_item_version 限定并通过 idempotency_key 幂等重放。选择或指令会准备一个精确的草稿，仍然通过正常的回复流程；此端点永远不会发送邮件。需要 assistant:write 范围。

通过不透明 ID 获取精确的操作预览

返回已准备的 Action 计划的精确回复身份、收件人、正文、承诺和副作用，以及其过期时间和源版本，以便客户端可以在用户通过现有回复端点使用 assistant_plan_id 发送之前显示将会发生什么。需要 assistant:read 范围。

获取内容最小化的助手 Activity

列出归属于调用者的近期交互和回执，不包含消息正文。需要 assistant:read 范围。

导出派生的助手数据

将分析、已接受的声明、Decision、交互、回执和模型使用情况导出为 JSON 附件。绝不包含源电子邮件正文或附件字节。需要 assistant:write 范围。还需要 email:auth_secrets（否则返回 403 INSUFFICIENT_SCOPE）：派生状态可能包含助手在身份验证邮件被排除之前从中提取的内容。

删除助手派生数据

幂等地删除派生智能、作业、模型使用情况、设备、导入和设置，同时保留源邮件。需要 assistant:write 授权。

{
  "ok": true,
  "deleted": {
    "work_items": 12,
    "claims": 40,
    "entities": 9,
    "jobs": 52
  },
  "source_mail_deleted": false
}

注册设备以接收已脱敏的 Now 提醒

为一个应用安装和环境注册或轮换加密的推送令牌。仅原生应用调用此接口，需要活跃的助手和 assistant:write 授权。

撤销设备注册

撤销一个安装的所有推送注册，例如在退出登录时。需要 assistant:write 授权。

检查电子邮件 DNS 运行状况（MX、SPF、DMARC、DKIM）

检查域的电子邮件 DNS 配置：MX 记录、SPF、DMARC 和 DKIM。从 MX 记录中自动检测电子邮件提供商（Google Workspace、Proton、Fastmail）。

{
  "domain": "mysite.com",
  "provider": "google-workspace",
  "mx": {
    "configured": true,
    "records": [
      "1 aspmx.l.google.com",
      "5 alt1.aspmx.l.google.com"
    ]
  },
  "spf": {
    "configured": true,
    "value": "v=spf1 include:_spf.google.com ~all"
  },
  "dmarc": {
    "configured": true,
    "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@mysite.com"
  },
  "dkim": {
    "configured": true,
    "selectors": [
      "google"
    ]
  }
}

curl https://domani.run/api/domains/mysite.com/email/check \
  -H "Authorization: Bearer domani_sk_xxx"

获取所有者范围内的电子邮件送达率健康状况

分别呈现确定性身份验证就绪度、按收件人加权的 30 天投递结果、帐户安全状态和实测服务商收件箱位置。就绪度分数并非进入收件箱的概率，未测量的位置返回为 not_tested。

curl https://domani.run/api/domains/mysite.com/email/deliverability \
  -H "Authorization: Bearer domani_sk_xxx"

在域上设置电子邮件

在域名上预配置电子邮件 DNS（可选）。当需要时，create_mailbox 会自动调用此函数。传递 force=true 以覆盖现有电子邮件提供商（Google Workspace、Fastmail、Proton）。

从域名中移除电子邮件

从域中删除电子邮件，删除所有邮箱和消息，并将 emailEnabled 设置为 false。此操作会更改整个域名的邮件，因此受邮箱限定的令牌会收到 403 MAILBOX_CONFINED。

检查电子邮件 DNS 状态

检查域的电子邮件 DNS 验证状态。返回域是否已验证并准备就绪、DNS 记录详细信息和邮箱计数。

在 domani.run 上创建邮箱

在 domani.run 上创建一个免费电子邮件地址（例如 hello@domani.run）。无需域名所有权。每个用户仅限 1 个免费 @domani.run 邮箱。许多常见的蛞蝓都是保留的。

列出所有邮箱

列出代理主体可以跨所有域访问的每个邮箱，包括工作区授权。

创建邮箱

创建一个电子邮件地址（邮箱）。提供完整的地址，例如“hello@mysite.com”。电子邮件 DNS 会在首次使用时自动配置。传递force=true来覆盖现有的电子邮件提供商。自定义域邮箱容量由活动帐户或工作区计划决定。每个帐户都可以使用 POST /api/email 单独创建一个免费的@domani.run 邮箱。 传递workspace_id 在您拥有的工作区中创建邮箱。对于自定义域，这会显式地、原子地将该域及其所有未指定范围的同级邮箱采用到该工作区中；域永远不能跨工作区分割。 通过 kind="hosted" 在您自己的域上创建真正的 IMAP/SMTP 邮箱（连接 Apple Mail、Thunderbird 或任何客户端），而不是默认的 API 邮箱（通过 API + webhooks 发送/接收）。托管邮箱返回要发布的 DNS 记录、邮件客户端设置和一次性应用程序密码。需要您拥有的域。

列出所有邮箱

列出代理主体可以访问的每个邮箱，包括工作区授权。与 GET /api/email 相同。

获取邮箱详细信息

通过完整电子邮件地址（URL 编码，例如 hello%40mysite.com）获取特定邮箱的详细信息。

更新邮箱

通过完整电子邮件地址更新邮箱的显示名称、Webhook URL 或转发电子邮件地址。设置为 null 以禁用/清除。

删除邮箱

通过完整电子邮件地址删除邮箱。请求正文中必须包含 confirm=true；否则返回包含 message_count 的预览。

发送电子邮件

从由完整电子邮件地址标识的邮箱发送电子邮件。服务器首先运行强制版本化策略：拒绝客观安全故障，同时返回声誉和内容质量结果作为警告。对于协作线程回复，传递撰写租约、观察到的reply_version和稳定的幂等性密钥；服务器在发送之前自动拒绝过时或重复的回复。每条消息最多 20 个唯一收件人。速率限制：每个邮箱每小时 100 个收件人。

对出站电子邮件进行预检

运行发送端点使用的确切版本化服务器端策略，而无需发送或消耗电子邮件配额。允许第三方域上的公共 HTTPS 身份验证链接，但带有信誉警告。本地/私有 URL、非 HTTPS 身份验证链接和可执行附件被阻止；超过 102 KB 的主体会产生剪辑警告。

列出电子邮件

在规范文件夹或虚拟视图中列出电子邮件。默认为收件箱。文件夹位置与邮件方向和垃圾邮件判定无关。 身份验证邮件（OTP/验证码、密码重置、魔术链接）标记为security: "auth"”。没有email:auth_secrets范围的令牌会看到那些主题和正文已隐藏（redacted: true）的消息 - 元数据（来自、日期）保持可见。subject、q 和 attachments 筛选条件只匹配调用方可以读取的内容：没有该范围时，此类邮件只按已隐藏的主题和正文匹配，因此搜索其中的验证码不会找到任何结果。

按含义和词语搜索邮件

搜索您可以读取的邮箱,或使用 mailbox 搜索一个邮箱。默认混合模式:消息嵌入(pgvector, cosine)和加权词语索引通过倒数排名融合,并带有少量时效性提升,在一条语句中完成;why 说明哪个分支匹配。q 中的 Gmail 运算符: from: to: cc: subject: label: filename: mailbox: is:unread|read|starred|unstarred has:attachment in:inbox|archive|sent|spam|trash|anywhere after:2026/08/01 before: newer_than:7d older_than:2w (h/d/w/m/y)、"a phrase"、排除用 -word 或 -from:、a OR b。仅由运算符组成的查询按最新优先列出匹配的消息(why: filter)。登录验证码和链接、垃圾邮件和系统邮件从不被索引;智能体的 search_opt_out_mailbox_ids 中列出的邮箱仅按词语搜索。绑定到智能体身份的令牌仅搜索其智能体操作的邮箱。需要 email:read。没有 email:auth_secrets 时，收到的身份验证邮件会在排序之前被排除：任何词语、运算符或筛选条件都不会匹配它，因此搜索登录验证码不会找到任何结果。

curl "https://domani.run/api/emails/search?q=facture+tucows+ao%C3%BBt&limit=5" \
  -H "Authorization: Bearer domani_sk_xxx"

开始连接 Gmail 收件箱

返回绑定到您的账户和导入界限的 Google 同意 URL。在浏览器中打开它；同意后，收件箱将成为其自己地址的已连接邮箱，在界限之后收到的邮件将被导入（默认：最近 24 小时），新邮件将在到达时跟随。永远不会导入整个收件箱：稍后使用 POST /api/emails/{address}/import 扩大范围。需要 email:write。服务器上必须配置 Google OAuth。

开始连接 Outlook 收件箱

返回绑定到您的账户和导入边界的 Microsoft 同意 URL。在浏览器中打开它;同意后,收件箱将成为其自身地址的已连接邮箱,边界之后收到的邮件将被导入(默认:最近 24 小时),新邮件会在到达时跟进。永远不会导入整个收件箱:稍后使用 POST /api/emails/{address}/import 扩大范围。需要 email:write。服务器上必须配置 Microsoft OAuth。

列出收件箱可以连接的方式

每个提供商一行（Gmail、Outlook、通过转发的任何收件箱、此处托管的地址）：连接如何开始（同意屏幕、转发规则、创建的地址），连接可以做什么（读取，或读取和写入），是否导入较旧的邮件，以及此服务器是否为其设置。仅当 configured 为 true 时显示连接按钮；reason 为操作员命名缺失的变量。需要 email:read。

通过转发连接收件箱

在收件箱自己的地址创建已连接的邮箱，并返回平台转发域上的转发地址，以及Gmail、Outlook和其他提供商的步骤。在提供商处添加转发规则；到达该地址的内容会被解包（原始发件人、日期、主题）并存储在已连接的邮箱下。Gmail会要求转发地址确认：代码和链接会出现在连接上。返回的第一封邮件，或探测（POST /api/emails/{address}/connector/verify），会使连接变为活动状态。只有新邮件会通过这种方式到达；旧邮件无法导入。需要email:write。转发域必须在服务器上配置。

通过转发规则发送探测

向已连接的收件箱发送邮件；当转发规则将其带回转发地址时，连接变为活动状态。仅适用于通过转发的连接。需要email:write。

读取已连接邮箱的连接

类型、状态、导入绑定、同步阶段(导入扫描,然后是历史记录)、导入进度(已扫描、已复制、待分析、已分析)、最后同步时间和最后错误。需要 email:read。转发确认（Gmail 的验证码和链接）属于身份验证邮件：没有 email:auth_secrets 时，其 code 和 url 为 null，并带有 redacted: true。受邮箱限定的令牌只能找到其自身的邮箱（否则返回 404）。

断开已连接邮箱的连接

删除个人自己的副本（消息、附件、搜索行、待处理作业）和凭据；保留邮箱行、标记为已断开连接的链接，以及智能体所做的操作（回执）。只有已连接的邮箱才能断开连接。需要 email:write。

导入已连接邮箱的较旧邮件

将导入扩展到更早的日期:新的导入运行会按到达顺序复制新绑定和当前绑定之间的邮件,在其自己的成本上限下进行。在导入扫描仍在运行时会被拒绝。需要 email:write。

按含义和词语搜索一个邮箱

与 GET /api/emails/search 相同的搜索,限制为此邮箱。需要 email:read。没有 email:auth_secrets 时，收到的身份验证邮件会在排序之前被排除：任何词语、运算符或筛选条件都不会匹配它，因此搜索登录验证码不会找到任何结果。

列出邮箱的对话

消息按照邮件客户端的分组方式分组:回复会加入其回复的消息的线程(In-Reply-To,然后是 References 链),没有可用标头的邮件会加入三十天内具有相同主题和共同通信者的最近线程,其他所有邮件会开始一个新线程,其 id 为其第一条消息的 id。线程按最后活动时间排序;垃圾箱和垃圾邮件永远不参与,除非被指定为文件夹。folder=inbox|archive|sent 保留在那里有消息的线程,但仍计算整个对话。

读取一个对话,最旧的消息在前

该线程的每条消息(包括垃圾箱,因此故事中不会缺少任何内容),包含其文本,最旧的在前,加上参与者和未读计数。Auth mail 的编辑方式与消息读取相同。

流式传输邮箱事件(服务器发送事件)

返回 text/event-stream。不带游标时流从当前时刻开始;带 since(来自 /api/email/changes 的游标或任何更早事件的 id)时,它首先重放该点之后的每个变更,然后实时跟踪邮箱日志:每帧携带变更类型作为事件名称(message.received、message.updated、message.deleted、message.moved、message.status、mailbox.resync_required、assistant.item.delegated、assistant.item.recalled 等),变更作为 JSON data 及其可恢复的 cursor,以及同一游标作为帧 id。首帧是 ready,包含用于恢复的游标;每 20 秒到达一次保活注释;连接在约 5 分钟后关闭,带有 close 帧和 retry: 提示。使用 Last-Event-ID(或 since)重新连接以无间隙、无重复地恢复。智能体令牌仅限于智能体操作的邮箱。关于由身份验证邮件生成的工作项的条目，对于没有 email:auth_secrets 的令牌，其 title 和 ask 会被隐藏。

列出电子邮件文件夹和计数

返回系统文件夹和虚拟视图的服务器派生计数，以及邮箱后端的生命周期功能。

对消息应用生命周期操作

移动、恢复、标记为已读、加注星标或永久删除最多 100 个显式消息 ID。移至垃圾箱是可逆的。永久删除需要email:delete，并且只接受垃圾箱中已有的邮件。每个响应都是持久操作收据，每个请求的 ID 都有一个结果。在标准Idempotency-Key标头或旧版idempotency_key JSON 字段中提供稳定的密钥，并在超时后重用它；精确的重试会返回存储的收据，而不会发生其他突变。如果提供了两种形式，则它们必须匹配。在不同的请求中重用密钥会返回 409。如果省略，服务器会创建一个密钥并在正文和Idempotency-Key标头中返回它。当只有部分批处理成功时，返回 207。

将消息标记为已读或未读

重试安全读取状态更新的兼容性端点。返回规范的持久每项操作收据以及遗留计数。超时后提供并重用Idempotency-Key标头或兼容性idempotency_key字段。

批量删除消息

可安全重试将邮件移至垃圾箱的兼容性端点。返回规范的持久每项操作收据以及遗留计数。超时后提供并重用Idempotency-Key标头或兼容性idempotency_key字段。

收到消息

按 ID 从由完整电子邮件地址标识的邮箱中获取单条消息。除非令牌具有 email:auth_secrets 范围，否则分类为身份验证邮件（OTP、密码重置、魔术链接）的消息将在主题/正文隐藏后返回。

删除一条消息

将邮件移至垃圾箱。这是可逆的。将生命周期操作与 delete_permanently 和 email:delete 令牌结合使用，以删除已在“垃圾箱”中的邮件。

回复消息

回复由完整电子邮件地址标识的邮箱中的邮件。线程标题是自动填充的，并且除非 quote 为 false，原始邮件会像邮件客户端一样引用在回复下方（使用账户语言的署名行、文本中的 > 行、HTML 中的 gmail_quote 块）。协作客户端应传递 compose 租约、观察到的reply_version 和稳定的幂等密钥；服务器在发送之前立即自动拒绝陈旧/双重回复。

转发消息

将邮件从由其完整电子邮件地址标识的邮箱转发给另一个收件人。转发身份验证邮件（OTP、密码重置、魔术链接）需要 email:auth_secrets 范围 - 它会泄露秘密。

获取邮箱头像信息

返回 Gravatar URL（如果设置）和由完整电子邮件地址标识的邮箱的注册链接。

获取邮箱 webhook 配置

返回 webhook URL、签名密钥、配置的身份验证标头名称以及邮箱状态。标头值永远不会返回。

设置邮箱 webhook

为 HMAC 签名的邮箱事件配置 HTTPS 目标：默认为入站邮件，另可（通过 events 选择加入）接收从该邮箱发出的邮件的投递结果。退信会在发送被接受后的几秒内送达发件人，而不是只留在消息记录里。实时入站投递会持久存储、立即尝试并最多重试 3 次。每次尝试都包括从 1 开始的 X-Domani-Delivery-Attempt。可选的授权或 X-API-Key 值会被加密并且永远不会返回；人类操作员应该通过 CLI 环境变量选项将它们提交到模型上下文之外。

curl -X PUT https://domani.run/api/emails/agent%40example.com/webhook \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://agent.example/webhook","events":["email.received","email.bounced","email.delivered"]}'

删除邮箱 webhook

从邮箱中删除 Webhook URL 和签名密钥。仅存储入站电子邮件。

旋转 webhook 签名秘密

重新生成邮箱 Webhook 的 HMAC-SHA256 签名密钥。旧秘密立即失效。

测试邮箱 webhook

将一个已签名的测试负载发送到邮箱 Webhook URL。返回 HTTP 状态以及投递是否成功。测试不会重试；实时入站投递最多重试 3 次。

列出邮箱别名

列出发送到邮箱的所有别名地址。别名允许多个地址（sales@、hello@、contact@）共享一个收件箱，而无需使用邮箱槽。

添加邮箱别名

添加传送到此邮箱的别名地址，而不使用邮箱槽。别名必须与邮箱位于同一域中。提供一个简单的地址（“sales”）或完整的地址（“sales@mysite.com”）。

删除邮箱别名

从邮箱中删除别名。发送到该地址的电子邮件将停止发送。

获取邮件客户端设置（托管）

获取托管邮箱的 IMAP/SMTP 连接设置，以配置 Apple Mail、Thunderbird 或任何邮件客户端。用户名是完整的地址；密码是应用程序密码（使用 POST /api/emails/{address}/credentials 创建一个）。仅托管邮箱。

列出应用程序密码（托管）

列出托管邮箱的应用程序密码。秘密仅在创建时显示一次；这仅返回标签和元数据。仅托管邮箱。

创建应用程序密码（托管）

为托管邮箱创建应用程序密码，用作邮件客户端 (IMAP/SMTP) 中的密码。秘密返回一次 - 现在存储它。仅托管邮箱。

撤销应用程序密码（托管）

撤销应用程序密码。任何使用它的邮件客户端都会立即停止连接。仅托管邮箱。

将邮件标记给人工

将邮件升级给帐户的人工（或使用 clear=true 清除标记）。在邮件上设置 needs_human，将其会话保持在 needs_human 状态，并触发 email.escalated Webhook + 应用内通知。这是 'answer the easy ones, stop on the one the human must decide' 背后的产品原语。

设置跟进提醒

在邮件上设置（或使用 clear=true 清除）一次性跟进提醒。当 remind_at 到达而邮件仍未得到答复时（入站：未发送回复；出站：未收到入站回复），email.reminder_due 会以 Webhook + 应用内通知的形式触发，并且提醒会自行清除。

列出联系人

帐户的通讯录，由邮件往来自动填充：通信者、邮件数量、最近活动和备注。默认按最近活跃排在最前（order=recent），用于展示：在分页扫描期间收到新邮件的联系人会移到游标之前，因此这次扫描可能会漏掉它。要同步整个通讯录，请传入 order=created：按创建时间再按 id 从旧到新排列，这个排序键永不改变，因此在整个扫描期间都存在的每个联系人都恰好返回一次，期间新建的联系人排在末尾。游标只能继续它所来自的排序（否则返回 400 INVALID_CURSOR）。会聚合每个邮箱的数据，因此受邮箱限定的令牌会被拒绝（400 MAILBOX_CONFINED）。

创建或更新联系人

保存联系人：设置显示名称并附加备注（'prefers short emails'、'decision maker at Acme'）。无论如何，邮件往来都会持续更新邮件数量。

删除联系人

从通讯录中移除联系人。如果对方再次来信，邮件往来会将其重新创建为自动联系人。

列出入站邮件规则

按应用的优先顺序列出邮箱的入站过滤规则（第一个匹配者获胜）。

添加入站邮件规则

添加一条规则，用于匹配字段（from/to/subject/body）的入站邮件。操作：drop、mark_read、forward（action_arg = 地址）、webhook_only（跳过转发）和 label（action_arg = 标签）。规则按优先级从低到高应用；第一条匹配规则生效。

删除入站邮件规则

从邮箱中删除入站过滤规则。

设置域包罗万象

将发送到域中不匹配地址的每封电子邮件路由到指定邮箱。任何与邮箱、子地址或别名不匹配的内容都会被捕获。该邮箱必须已存在于域中。此操作会更改整个域名的邮件，因此受邮箱限定的令牌会收到 403 MAILBOX_CONFINED。

清晰的域名包罗万象

删除域上的所有内容。发送至不匹配地址的电子邮件将再次被丢弃。此操作会更改整个域名的邮件，因此受邮箱限定的令牌会收到 403 MAILBOX_CONFINED。

增量同步一个邮箱

不使用游标进行调用以捕获有界完整快照之前的基线。然后传递next_cursor来重放该快照期间和之后发生的突变。游标是不透明的、签名的、邮箱绑定的，并在 30 天后过期。推送通知只是失效提示；该期刊是持久恢复来源。关于由身份验证邮件生成的工作项的条目，对于没有 email:auth_secrets 的令牌，其 title 和 ask 会被隐藏。

列出被抑制的地址

在禁止列表中列出地址 - 硬退回邮件和投诉（从递送事件中自动提取）以及手动输入。发送到这些地址的邮件将被跳过。光标分页。

添加抑制

手动将地址添加到禁止列表中，以便将来的发送跳过它。自动添加硬退回邮件和投诉；将此用于您想要停止发送电子邮件的地址。幂等。

移除抑制

从黑名单中删除某个地址，以便您可以再次通过电子邮件发送该地址（例如，在收件人修复其邮箱后）。

请求工作区所有权转让

仅限域名所有者。向现有会员发送 48 小时接受链接。在经过身份验证的成员接受之前，不会发生任何变化。

撤销待定的所有权转让

接受工作区所有权

仅限目标。以原子方式传输工作空间、范围域和邮箱；以前的所有者成为管理员，现有的付款人保持不变。

创建一个新帐户

通过发送登录邮件链接开始创建新账户（或登录已有账户）；此处不会返回API密钥。在浏览器中点击该链接的人会直接进入已登录状态的控制台。没有浏览器会话的CLI或智能体应改用设备登录流程（先 POST /api/auth/cli 再轮询 GET /api/auth/cli/poll），该流程会通过邮件发送同样的批准，并在批准后返回API密钥 - 响应中的 next_steps 会说明这一点。传入 ref 代码会将新用户永久关联到推荐人 - 推荐人将从该用户此后所有的域名购买中获得佣金。

{
  "ok": true,
  "verification_required": true,
  "message": "Check your email for a sign-in link to finish creating your account.",
  "hint": "A human must open that email and click the link in a browser to finish verification; no API key is issued yet.",
  "next_steps": [
    "If a person can click the email link, nothing else to do: they land on the dashboard already signed in.",
    "If you are a CLI or agent without a browser session, start a device-login flow instead: POST /api/auth/cli, then poll GET /api/auth/cli/poll?code=... until status is \"complete\" - the same email approves it and hands back an API key, no browser needed on your side."
  ]
}

curl -X POST https://domani.run/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

发送魔术链接登录电子邮件

将登录链接发送到提供的电子邮件。如果用户不存在，请先创建一个帐户。魔术链接重定向到带有身份验证凭据的仪表板。对于编程式 API 访问，请使用 POST /api/auth/register 直接获取 API 密钥。

{
  "ok": true,
  "message": "Check your email for a sign-in link."
}

curl -X POST https://domani.run/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

验证魔法链接令牌

验证魔术链接令牌并使用身份验证凭据重定向到仪表板。由魔术链接电子邮件使用 - 通常不由智能体直接调用。智能体应改用 POST /api/auth/register。

生成一次性跨主机登录代码

仅限浏览器：让已在 domani.run 或 mailzero.run 登录的用户无需第二封魔法链接即可在另一个主机上恢复会话。返回一个 URL，其片段携带一个有效期 60 秒、一次性且绑定主机的代码；该代码从不写入日志，也不会通过查询字符串发送。在浏览器会话之外没有用处，因此不作为智能体工具公开。

{
  "url": "https://mailzero.run/auth/handoff#code=xxx&next=%2Finbox"
}

兑换一次性跨主机登录代码

仅限浏览器：由目标主机上的 /auth/handoff 页面调用，用 URL 片段中的代码换取会话，与 GET /api/auth/verify 处理魔法链接的方式完全相同。代码必须与此请求到达的 Host 一致。不是智能体工具。

{
  "ok": true,
  "next": "/inbox"
}

获取当前帐户详细信息

返回经过身份验证的用户的帐户信息，包括电子邮件、付款状态、联系信息状态、推荐代码和使用计数。智能体应在身份验证后调用此方法，以在尝试购买之前检查has_payment_method和has_contact。

{
  "id": "cm5abc123",
  "email": "dev@example.com",
  "plan": "agent",
  "workspace_plans": [
    "mail_pro"
  ],
  "has_payment_method": true,
  "has_contact": true,
  "referral_code": "x7k9m2",
  "referral_rate": 20,
  "domain_count": 3,
  "token_count": 2,
  "created_at": "2025-01-15T10:30:00.000Z"
}

curl https://domani.run/api/me \
  -H "Authorization: Bearer domani_sk_xxx"

更新帐户偏好设置

更新经过身份验证的用户的首选付款方式和/或 BCP 47 区域设置。 API 响应保持结构化且不进行翻译。

删除帐户（在持有域名时被阻止）

永久删除经过身份验证的用户的帐户、令牌、Webhooks、邮箱和其他应用程序数据。注册的域不会随帐户一起删除：请求失败并显示 409 HAS_DOMAINS，直到每个域都转出。此操作无法撤消。

获取真实的激活状态和建议的下一步操作

返回服务器派生的产品里程碑和功能感知的下一步操作。令牌创建、令牌使用、页面浏览量和客户端清单状态均被故意排除。

curl https://domani.run/api/me/activation \
  -H "Authorization: Bearer domani_sk_xxx"

取消或恢复首轮指导

仅存储呈现首选项。它无法完成产品里程碑。

获取注册者联系信息

返回已认证用户的 WHOIS 注册人联系信息。购买时为可选 (在设置之前，由 Domani 的联系人代表用户持有新域名)，转入域名之前为必填。

{
  "has_contact": true,
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US",
    "phone": "+1.2125551234",
    "email": "jane@example.com"
  }
}

curl https://domani.run/api/me/contact \
  -H "Authorization: Bearer domani_sk_xxx"

设置注册者联系信息

设置或更新你的 WHOIS 注册人联系信息。购买时为可选，转入域名之前为必填。它会成为你的域名的注册人和账单联系人：在设置之前，由 Domani 的联系人代表你持有这些域名。更新后，新的联系信息会推送到支持联系人变更的注册商处你的所有有效域名，使你成为这些域名的注册人；注册商可能会发邮件请你在 15 天内确认。

curl -X PUT https://domani.run/api/me/contact \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jane","last_name":"Doe","address1":"123 Main St","city":"New York","state":"NY","postal_code":"10001","country":"US","phone":"+1.2125551234","email":"jane@example.com"}'

重新发送联系电子邮件验证

重新发送帐户联系电子邮件地址的验证电子邮件。每封电子邮件的频率限制为每 15 分钟一次。

列出已登录的设备

已登录该账户的每个浏览器、移动应用和终端，调用方自己的会话排在最前 (current)。每次登录都会打开独立的会话，因此在新设备上登录绝不会让其他设备退出。位置是设备登录时所在的地点（根据其 IP 得出的国家和城市），未知时省略。API 密钥不是会话：请使用 GET /api/tokens 列出。

{
  "sessions": [
    {
      "id": "cm5ses123",
      "current": true,
      "kind": "web",
      "product": "domani",
      "device": {
        "type": "desktop",
        "os": "macOS",
        "browser": "Chrome"
      },
      "location": {
        "country": "FR",
        "city": "Paris"
      },
      "signed_in_at": "2026-10-01T10:00:00.000Z",
      "last_active_at": "2026-10-18T09:12:00.000Z"
    },
    {
      "id": "cm5ses456",
      "current": false,
      "kind": "mobile",
      "product": null,
      "device": {
        "type": "mobile",
        "os": "iOS",
        "browser": null
      },
      "location": {
        "country": "FR",
        "city": "Lyon"
      },
      "signed_in_at": "2026-09-20T18:30:00.000Z",
      "last_active_at": "2026-10-17T21:04:00.000Z"
    }
  ],
  "hint": "Sign a device out with DELETE /api/sessions/{id}, or every device but this one with DELETE /api/sessions."
}

curl https://domani.run/api/sessions \
  -H "Authorization: Bearer domani_sk_xxx"

让其他所有设备退出登录

让账户中除发起请求的会话以外的所有会话退出登录。这些设备在下一次请求时需要重新登录。API 密钥保持不变。

{
  "revoked": 2,
  "hint": "Every other device is signed out. API keys are unchanged."
}

curl -X DELETE https://domani.run/api/sessions \
  -H "Authorization: Bearer domani_sk_xxx"

让设备退出登录

让一个会话退出登录。current 指发起请求的会话（自己退出无需任何范围）；其他任何会话都需要 tokens:write。

{
  "success": true,
  "current": false,
  "hint": "That device is signed out and will be asked to sign in again."
}

curl -X DELETE https://domani.run/api/sessions/cm5ses456 \
  -H "Authorization: Bearer domani_sk_xxx"

列出智能体身份的 API 令牌

绑定到此智能体身份的令牌（掩码密钥、作用域、邮箱限制、最后使用时间）。智能体绑定令牌是该智能体对每个 assistant 和邮件界面的视图。

一次调用为智能体提供其自己的 API 密钥

创建绑定到此智能体身份的令牌，限制在智能体操作的邮箱内，具有智能体所需的最小作用域（assistant:read、assistant:write、email:read、email:write）。使用该密钥，智能体只能读取自己的 Today、其邮箱和交给它的项目；命名另一个智能体会返回 403，仅限所有者的路由（设置、回填、导出）会拒绝它。完整密钥仅在此响应中返回。需要 tokens:write。不运营任何邮箱的智能体默认不会获得邮件范围，请求这些范围会返回 400 AGENT_MAILBOXES_REQUIRED：没有邮箱的密钥将能访问该帐户的所有邮箱。

curl -X POST https://domani.run/api/agents/identity/dave/tokens \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dave on the laptop"}'

撤销智能体的 API 令牌

撤销绑定到此智能体身份的令牌。它会立即停止工作。需要 tokens:write。

列出您的 API 令牌

返回经过身份验证的用户的所有 API 令牌。为了安全起见，密钥被屏蔽（前 12 个 + 后 4 个字符可见）。使用它来审核活动令牌。

{
  "tokens": [
    {
      "id": "cm5abc123",
      "name": "Default",
      "key": "domani_sk_a...wxyz",
      "lastUsed": "2025-02-18T10:30:00.000Z",
      "expiresAt": null,
      "expired": false,
      "scopes": [
        "*"
      ],
      "createdAt": "2025-01-15T10:30:00.000Z",
      "max_per_tx": null,
      "max_per_month": null,
      "spent_this_month": 0,
      "parent_token_id": null,
      "agent_identity": null
    },
    {
      "id": "cm5def456",
      "name": "CI/CD",
      "key": "domani_sk_b...vwxy",
      "lastUsed": null,
      "expiresAt": "2025-05-01T14:00:00.000Z",
      "expired": false,
      "scopes": [
        "domains:read",
        "domains:write"
      ],
      "createdAt": "2025-02-01T14:00:00.000Z"
    }
  ]
}

curl https://domani.run/api/tokens \
  -H "Authorization: Bearer domani_sk_xxx"

创建新的 API 令牌

创建一个新的 API 令牌。仅在此响应中返回完整密钥 - 安全地存储它。您可以创建多个令牌来分隔不同应用程序的访问。

{
  "id": "cm5ghi789",
  "name": "CI/CD Pipeline",
  "key": "domani_sk_x1Y2z3A4b5C6d7E8f9G0hIjK",
  "expiresAt": "2025-03-20T10:30:00.000Z",
  "scopes": [
    "domains:read",
    "domains:write"
  ],
  "createdAt": "2025-02-18T10:30:00.000Z",
  "max_per_tx": 25,
  "max_per_month": 100,
  "mailbox_ids": [],
  "http_route_policy": null
}

curl -X POST https://domani.run/api/tokens \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline"}'

撤销 API 令牌

永久撤销 API 令牌。任何使用此令牌的应用程序将立即失去访问权限。此操作无法撤消。

{
  "success": true
}

curl -X DELETE https://domani.run/api/tokens/cm5abc123 \
  -H "Authorization: Bearer domani_sk_xxx"

列出安全审核事件

按从新到旧返回账户安全审计记录，包括令牌生命周期（创建、撤销、提权尝试）、支出上限和 max_price 拒绝、扣款、付款请求以及被阻止的账户删除。可用于监控智能体令牌的行为。

{
  "events": [
    {
      "id": "evt1",
      "tokenId": "cm5abc123",
      "type": "purchase.charged",
      "targetType": "domain",
      "targetId": "mysite.com",
      "metadata": {
        "amountCents": 1450,
        "operation": "buy",
        "method": "card"
      },
      "createdAt": "2026-07-11T10:00:00.000Z"
    },
    {
      "id": "evt2",
      "tokenId": "cm5abc123",
      "type": "purchase.denied_cap",
      "targetType": "domain",
      "targetId": "expensive.ai",
      "metadata": {
        "amountCents": 8470
      },
      "createdAt": "2026-07-11T09:58:00.000Z"
    }
  ],
  "next_cursor": null,
  "hint": "Security-relevant events for this account."
}

curl "https://domani.run/api/audit?limit=50" \
  -H "Authorization: Bearer domani_sk_xxx"

列出网络钩子

列出为您的帐户配置的所有 Webhook 端点。返回每个 Webhook 的 URL、订阅事件和活动状态。秘密在创建后永远不会返回。受邮箱限定的令牌只能看到限定在其自身邮箱内的 Webhook。

{
  "webhooks": [
    {
      "id": "cm5wh001",
      "url": "https://example.com/webhooks/domani",
      "events": [
        "domain.purchased",
        "dns.updated"
      ],
      "active": true,
      "created_at": "2026-02-25T10:00:00.000Z"
    }
  ],
  "hint": "1 webhook(s)."
}

curl https://domani.run/api/webhooks \
  -H "Authorization: Bearer domani_sk_xxx"

创建网络钩子

注册新的 HTTPS Webhook 端点。可选的授权或 X-API-Key 值静态加密并包含在每次投递中。签名秘密仅返回一次。每个帐户最多 5 个 Webhook。由受邮箱限定的令牌创建的 Webhook 会被限定在相同的邮箱内：它不会收到任何其他邮箱的邮件事件。

{
  "id": "cm5wh001",
  "url": "https://example.com/webhooks/domani",
  "events": [
    "domain.purchased",
    "dns.updated"
  ],
  "secret": "whsec_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "active": true,
  "created_at": "2026-02-25T10:00:00.000Z",
  "hint": "Webhook created. Save the secret - it won't be shown again. Use it to verify incoming payloads with HMAC-SHA256."
}

curl -X POST https://domani.run/api/webhooks \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","events":["domain.purchased","dns.updated"],"headers":{"Authorization":"Bearer sender_key_xxx"}}'

更新网络钩子

更新 Webhook 的 URL、订阅事件、活动状态或加密的身份验证标头。仅发送您要更改的字段。受邮箱限定的令牌只能访问限定在其自身邮箱内的 Webhook（否则返回 404）。

删除网络钩子

删除 Webhook 端点。所有待处理的投递都将被取消。此操作无法撤消。受邮箱限定的令牌只能访问限定在其自身邮箱内的 Webhook（否则返回 404）。

列出 webhook 投递

获取 Webhook 最近的投递尝试。显示事件类型、HTTP 状态、尝试次数和任何错误。对于调试失败的投递很有用。受邮箱限定的令牌只能访问限定在其自身邮箱内的 Webhook（否则返回 404）。

{
  "deliveries": [
    {
      "id": "cm5del001",
      "replay_of_id": null,
      "event_type": "domain.purchased",
      "status": "delivered",
      "http_status": 200,
      "attempts": 1,
      "last_error": null,
      "created_at": "2026-02-25T10:05:00.000Z"
    }
  ],
  "hint": "1 delivery(ies) for this webhook."
}

重播 webhook 投递

克隆并立即重新传递不可变的 Webhook 事件。事件负载和事件 ID 保持相同； HMAC 签名收到新的时间戳。所需的幂等性密钥可保证调用者重试不会发送两次。受邮箱限定的令牌只能访问限定在其自身邮箱内的 Webhook（否则返回 404）。相同负载有一个例外：从身份验证邮件复制的主题会以隐藏形式发送，因为 Webhook 的 URL 可能自首次投递以来已经更改。

列出 Webhook 事件类型

列出所有可用的 Webhook 事件类型及其说明。无需身份验证。

{
  "events": [
    {
      "type": "domain.purchased",
      "description": "A new domain was successfully registered"
    },
    {
      "type": "dns.updated",
      "description": "DNS records were changed for a domain"
    },
    {
      "type": "transfer.completed",
      "description": "A domain transfer completed successfully"
    }
  ]
}

curl https://domani.run/api/webhooks/events

列出通知

使用基于光标的分页列出您的应用内通知。包括交易事件、挂牌更新和系统警报。 需要notifications:read范围。 在邮件主题于写入时隐藏之前写下的通知，对于没有 email:auth_secrets 的令牌，其 body 和 data.subject 中身份验证邮件的主题会以隐藏形式读取。

获取未读通知数

用于轮询未读通知计数的轻量级端点。 需要notifications:read范围。

{
  "unread_count": 3
}

将通知标记为已读

将单个通知标记为已读。 需要notifications:read范围。

将所有通知标记为已读

将所有未读通知标记为已读。 需要notifications:read范围。

获取通知首选项

返回用户对每个类别和渠道（in_app、email）的通知偏好。缺少的偏好默认启用。 需要 notifications:read 范围。

更新通知首选项

更新特定类别和渠道的通知首选项。 需要notifications:read范围。