通过 API 和 MCP 管理邮件应用专用密码

REST API 和 MCP 可列出、创建、替换和撤销普通邮箱的应用专用密码，更改邮件应用登录模式，并设置未来新邮箱的账户默认值。本页供集成开发参考。控制面板和网页邮箱操作说明请参阅为邮件应用和设备创建应用专用密码。

应用专用密码可用于 IMAP、端口 465 和 587 的 SMTP、ManageSieve 及 CalDAV/CardDAV。它不能用于登录新网页邮箱或控制面板。经典网页邮箱通过 IMAP 登录，接受应用专用密码。邮箱 2FA 仅保护新网页邮箱登录；邮件应用和经典网页邮箱不会要求其验证码。

此功能没有独立的邮箱套餐限制。现有 API 和 MCP 套餐权限仍适用；参阅 API 权限范围与权限。

身份验证、权限范围与成员权限

对 /api/v1 下的 REST 请求使用 Bearer 令牌。JSON 写入使用 Content-Type: application/json 和 Idempotency-Key 标头。

除令牌的 API 权限范围外，还会检查成员角色中的密码设置权限。这适用于成员令牌及由成员授权的连接器。所有者令牌不需要额外的密码设置权限范围。成员缺少该权限时，返回 403 scope_blocked_by_membership。

托管 OAuth 连接器可使用对应的 REST 能力权限范围。在旧版权限包中，mail:read 提供 mailboxes:read 和 account:read；mail:write 还提供 mailboxes:write。权限范围扩展不会覆盖成员权限或仅限所有者的规则。

令牌的 domain_ids 和 mailbox_ids 限制同样适用，包括批量选择。功能关闭时，应用专用密码 endpoint 和两个模式 endpoint 会在身份验证及中间件检查后返回 404 not_found。无法访问或不存在的邮箱也返回 404，因此不要将所有 404 都视为功能状态信号。

Endpoint 速查

以下路径包含 /api/v1 前缀。{mailbox} 是普通邮箱 ID；{id} 是属于该邮箱的应用专用密码记录 ID。

表中所有写入均要求 Idempotency-Key。密码 endpoint 是已有的管理员重置操作，与应用专用密码轮换不同。

列出应用专用密码并理解记录字段

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

响应包含顶层字段 mailbox_id、client_auth_mode、limit、active_count，以及记录数组 data。limit 为每个邮箱 25 个有效密码。有效记录排在前面，最新的优先；已撤销记录保留 90 天。列表响应绝不包含密码本身。

每条记录包含：

公开的撤销原因包括 revoked、rotated、mailbox_password_reset、mailbox_password_changed、login_suspended、converted_to_shared 和 mailbox_trashed。列表不包含平台内部生成的凭据。

创建应用专用密码

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

name 为必填字段，要求 1 至 64 个可打印字符。连续空白字符会合并为一个空格。邮箱必须是有效的普通邮箱，登录未暂停，且有效应用专用密码少于 25 个。

201 响应在 data 下包含完整记录，增加 data.password，并包含 message。例如，响应中的凭据字段如下：

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

此示例省略了上文所述的其他记录字段。示例密码仅作说明。实际密码由 16 个自动生成的小写字母组成，返回时不含空格。应用也接受空格和大写字母；向用户显示时可分为四组，每组四个字母。

密码只返回一次。不要将它写入应用日志。用户直接在邮件应用中输入它，并以完整邮箱地址作为用户名。创建和替换会向邮箱及已设置的恢复邮箱发送通知，写明密码名称，但不包含密码本身。随新邮箱一起签发的第一个应用专用密码是例外（见下文）。

连接设置请使用邮件客户端设置 API。下载的 Apple 描述文件不含密码；macOS 或 iOS 在安装时询问后，由用户输入应用专用密码。

创建邮箱时获取第一个应用专用密码

POST /api/v1/mailboxes 和 POST /api/v1/mailboxes:bulk 接受可选的布尔字段 create_app_password。设为 true 时，每个新建邮箱还会获得第一个应用专用密码，并以 app_password 返回一次，内容为上文所述的记录字段加上 password。它的名称为 Created with the mailbox，且不会为它发送通知邮件，因为邮箱是新建的，调用方刚刚收到了它的密码。不传该字段（默认 false）时，响应不变。未启用应用专用密码时会忽略该字段。

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

此时 201 响应包含 one_time_password（用于网页邮箱的邮箱密码）以及供邮件应用使用的 app_password.password。在批量响应中，每个新建行都有自己的 app_password。如果无法签发，app_password 为 null（单个创建还会添加 _app_password_warning）；邮箱仍会创建，你可以使用上文的端点 创建一个。使用相同 Idempotency-Key 原样重试单个创建，会返回包含两个密码的相同响应，且不会签发第二个应用专用密码。批量重放会省略密码，与 one_time_password 的处理方式相同。

替换或撤销密码

替换不需要 JSON 请求体：

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

200 响应在 data 下包含新的完整记录、一次性 data.password，并在顶层包含指向旧记录的 replaced_id 和 message。替换后的记录有新的 data.id，名称保持不变。旧记录以 revoked_reason: "rotated" 撤销，旧密码立即失效，使用它的应用会退出登录。请在设备上更新为新密码。

撤销而不生成替换密码：

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

无需请求体。200 响应包含 status: "revoked"，并在 data 下包含完整的已撤销记录。该应用失去访问权限；其他使用有效应用专用密码的设备会自动重新连接。撤销无法撤回。使用新请求尝试替换或撤销已撤销的记录，会返回 409 conflict。

更改单个邮箱的邮件应用登录模式

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

mode 为必填字段，接受：

• app_password_only：邮件应用必须使用应用专用密码。使用邮箱密码的连接会退出登录；使用有效应用专用密码的应用会自动重新连接。
• password_or_app_password：邮件应用接受邮箱密码或应用专用密码。

200 响应包含 mailbox_id、client_auth_mode 和 message。再次设置当前模式会返回 200，不做任何更改。更改模式不会撤销现有应用专用密码。

请先为设备创建密码，再将其设为必需。邮箱密码登录被拒绝时，可能显示："Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords." （登录失败。此邮箱仅接受应用专用密码：请在网页邮箱的设置 > 应用专用密码中创建一个。） 有些应用只显示一般的密码错误。

共享邮箱没有直接登录，此 endpoint 返回 422 mailbox_not_eligible。平台系统邮箱不能切换至 app_password_only，否则返回 422 system_mailbox_protected。

两种模式都不会更改新网页邮箱登录、所有收件箱、Message API 令牌、导入此邮箱的迁移、邮件规则或转发。共享邮箱成员使用自己普通邮箱的凭据和模式。

批量更改模式

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

提供 mode，并且只提供一个选择器：

账户和令牌限制会缩小每次选择范围。明确指定的 ID 不可访问或不存在时，返回 404，而不是部分应用选择。未知域名或其他账户的域名返回 422 validation_error。没有选择器或提供多个选择器时，返回 422 invalid_selection。

最多可匹配 1000 个邮箱。选择范围更大时，会在任何更改前返回 422 selection_too_large。请缩小域名选择范围，或发送明确的分批列表。

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

matched 统计选中的邮箱；updated 统计实际更改模式的邮箱；skipped 统计共享邮箱、已移至最近删除或正在删除的邮箱，以及要求应用专用密码时的平台系统邮箱。暂停运行或暂停登录的邮箱可以预先更新模式，待访问恢复时生效。已匹配目标模式的邮箱计入 matched，但不计入 updated 或 skipped，因此可安全重复操作。被暂停的账户会收到 403 拒绝响应。

读取邮箱状态并设置账户默认值

应用专用密码功能开启时，GET /api/v1/mailboxes 和 GET /api/v1/mailboxes/{mailbox} 的邮箱资源包含以下字段：

• client_auth_mode：app_password_only 或 password_or_app_password。
• app_passwords_count：可见且有效的应用专用密码数量，整数，不含平台内部凭据。

功能关闭时省略这两个字段。共享邮箱没有可用的直接登录模式或应用专用密码；请改为获取普通成员邮箱的凭据。

GET /api/v1/account 要求 account:read。正常顶层字段仍可用：id、name、email、plan、effective_plan_slug、subscription_status、limits、features、usage、safety_limits 和 created_at。只有应用专用密码开启，且平台将账户默认设置应用于新邮箱时，才增加 new_mailbox_client_auth_mode。否则 GET 仍可用，但省略此字段。

只有账户所有者可更改默认设置：

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

必填字段接受相同的两种模式。它是此处唯一可写的账户字段。响应包含顶层 id、new_mailbox_client_auth_mode 和 message。若不同时满足公开该字段的两个条件，PATCH 返回 404；任何成员令牌或成员授权的连接器都会收到 403 scope_blocked_by_membership。

通过 domain_ids 或 mailbox_ids 限制的所有者令牌会收到 403 token_resource_constrained。请使用不受资源限制的所有者令牌，或在账户设置中更改默认设置。

默认设置影响未来由控制面板、批量操作、邀请、API 和智能体创建的邮箱，绝不会更改现有邮箱。通过 API 单独创建邮箱时，可在 POST /api/v1/mailboxes 中明确提供 client_auth_mode；省略时采用账户默认值。现有邮箱在功能上线后保留 password_or_app_password。新邮箱默认值为 app_password_only，除非账户所有者更改。

重置邮箱密码会自动撤销应用专用密码

POST /api/v1/mailboxes/{mailbox}/password 要求 mailboxes:write、相同的成员密码设置权限，以及 Idempotency-Key。请求体必须提供 password，即符合邮箱密码策略的新邮箱密码。这不是创建应用专用密码的 endpoint。

通过此 endpoint 成功执行的每次管理员重置，包括 MCP 智能体更改密码，都会以 mailbox_password_reset 原因撤销所有应用专用密码，无法选择保留。功能开启时，响应包含整数计数 app_passwords_revoked，以及 status、sync_pending 和 message：

• 邮件服务器同步完成时，返回 200、status: "updated"、sync_pending: false。
• 密码已保存但同步待完成时，返回 202、status: "update_pending"、sync_pending: true。此时应用专用密码已被撤销。

重置也会撤销邮箱现有的消息令牌。这是重置邮箱密码的结果，不是轮换单个应用专用密码或更改邮件应用模式的结果。

用户在网页邮箱中自助更改密码时，仅在勾选同时撤销所有应用专用密码后才撤销应用专用密码。密码恢复、暂停登录、转为共享邮箱、移至最近删除会撤销所有应用专用密码。恢复访问或邮箱不会恢复已撤销的密码。参阅通过 API 暂停邮箱登录。

幂等性和一次性密码

每次主动写入都使用新的 Idempotency-Key，仅在因传输问题重试相同方法、路径和请求体时复用。密钥为必填项，最多 255 个字符。成功响应默认缓存 24 小时；将同一密钥用于不同请求会返回 409 idempotency_mismatch。

重放应用专用密码创建或轮换请求时，会返回相同的安全标识符，但省略 data.password，并包含 _idempotency_replay_warning 和响应标头 X-Idempotency-Replayed: true。重放无法取回丢失的密码。请使用返回的 data.id，以新密钥轮换有效记录，获取可用的替换密码。轮换后请记录新 ID。

使用同一密钥重放成功的撤销请求，会返回已保存的结果。对已撤销记录发出新的撤销请求，会返回 409 conflict。模式更改本身可重复，但每次主动更改都应使用新密钥：切换模式后复用旧密钥，可能重放旧响应，而不会执行新的更改意图。

请求限额与错误

创建限额为每个账户每小时 60 次，替换限额为每个账户每小时 30 次。API 和 MCP 调用者共享这些账户限额，每个令牌不会各有一份。批量模式更改另有每分钟 10 次请求限制。正常 API 限流也适用于这些路由，默认每个凭据每分钟 60 次请求。被限流的请求返回 429 rate_limited；请按 Retry-After 标头等待后再重试。

错误使用标准 error 对象，包含 code、message、hint、request_id 和 retryable。请处理机器可读代码，而不是匹配消息文本。

MCP 工具与修改操作控制

MCP 使用相同的 REST 授权规则和响应字段。直接工具如下：

邮箱创建工具 create_mailbox_generated_password 和 bulk_create_mailboxes 也接受与 REST 相同的可选输入 create_app_password。

写入工具也接受可选的 idempotency_key。REST 更改邮箱模式使用请求体字段 mode；MCP 工具将该输入称为 client_auth_mode。其批量选择器遵循与 REST 相同的访问规则和 1000 个邮箱上限。

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

自托管服务器中，上述每个写入都要求 TREKMAIL_ALLOW_DESTRUCTIVE=true。创建凭据也受此控制，因为它会授予邮箱访问权限。列出密码和读取账户不需要该标志。调用写入前，请用户批准计划中的凭据或访问更改。直接返回密码的工具会要求智能体只显示一次密码，让用户粘贴到应用中，且不得保存到文件或记忆中，也不得在后续消息或工具调用中重复。

ChatGPT/OpenAI 和 Claude 目录配置

创建和替换时，这些配置提供安全的控制面板设置链接，而不是在聊天中生成密码。在这些配置中，创建邮箱同样通过控制面板链接完成，因此第一个应用专用密码来自控制面板的邮箱已创建卡片，而不是 create_app_password。目标地址为 /app/mailboxes/{mailbox_id}/security#app-passwords；用户登录后在那里完成操作。

OpenAI 配置提供 get_mailbox_app_password_setup_link 和 get_mailbox_app_password_replacement_setup_link。Claude 配置保留 create_mailbox_app_password 和 rotate_mailbox_app_password 名称，但返回安全设置链接，而不是 data.password。不要承诺这些目录工具会返回密码，也不要要求用户将密码粘贴到对话中。

获取连接参数请使用 get_mail_client_setup。一般连接器设置请参阅连接 AI 智能体。White Label 邮箱使用相同的 API 功能，以及品牌网页邮箱和邮件主机；面向用户的说明中，将该凭据称为应用专用密码。