API Key 域名策略升级说明

这次更新只聚焦 API Key 域名策略本身，不再把邮件展示、域名引导、公开页面稳定性这些用户侧优化混在同一篇文章里。

一、为什么要改

旧版本里，domainScope 同时承担了两件事：

1. 这把 API Key 能访问哪些域名
2. 当请求没有传 domain 时，系统从哪里随机挑一个域名

这会带来一个很别扭的问题：

• 你把某个自有域名共享出去，只是想让别人能用
• 但自己的 API Key 在省略 domain 时，也可能随机落到这个共享域名上

这次升级的目标，就是把这个默认行为收得更合理。

现在的选择顺序是什么

从现在开始，POST /v1/accounts 在省略 domain 时，会按下面的顺序决定最终域名：

1. 如果请求体显式传了 domain，永远优先使用它
2. 如果这把 API Key 设置了 defaultDomainId，优先使用默认域名
3. 如果没有默认域名，再按当前 domainScope 的自动策略选择

各种 scope 的自动选择规则

二、新增的默认域名字段

defaultDomainId 是做什么的

创建 API Key 时，现在支持一个新的可选字段：

{
  "name": "Mailer Worker",
  "permissions": ["read", "write"],
  "domainScope": "own",
  "defaultDomainId": "domain_private_001"
}

它解决的是什么问题

它的作用是：

• 这把 Key 省略 domain 时，优先固定到你指定的默认域名
• 避免“同一把 Key 今天落这个域名，明天落另一个域名”的随机感
• 避免共享域名在默认行为里被误选
• 让 worker、脚本和第三方集成更稳定

兼容性说明

这意味着：

• 如果你之前一直在请求体里明确传 domain，这次不会影响你
• 如果你依赖旧版本“省略 domain 后随机挑一个共享域名”，建议尽快改成：
  • 显式传 domain
  • 或者给这把 Key 设置 defaultDomainId

三、控制台里你会看到什么变化

这次控制台里的 API Key 创建页也一起增强了：

• 域名范围和默认域名分开显示，不再混在一起
• 域名选择器会标注：
  • 私有自有域名
  • 已共享的自有域名
  • 公共 / 共享域名
• “立即试一下”的示例请求会按当前配置自动更新
• 如果设置了默认域名，示例会明确告诉你：请求省略 domain 时会优先使用哪个域名

四、开发者该怎么调整现有集成

如果你已经在生产环境使用 API Key 创建临时邮箱，建议你对照下面这张清单快速看一遍：

1. 这把 Key 的 domainScope 是否真的符合用途
2. 你是否需要一个固定的 defaultDomainId
3. 如果你之前依赖“省略 domain 随机落共享域名”，现在是否要改成显式传 domain

示例一：给一把 Key 固定默认域名

curl https://maliapi.215.im/v1/me/api-keys \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mailer Worker",
    "permissions": ["read", "write"],
    "domainScope": "own",
    "defaultDomainId": "domain_private_001"
  }'

后续调用：

curl https://maliapi.215.im/v1/accounts \
  -X POST \
  -H "X-API-Key: AC-your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"address":"demo"}'

即使你没有传 domain，系统也会优先使用 domain_private_001。

示例二：指定域名集合，同时固定默认域名

curl https://maliapi.215.im/v1/me/api-keys \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Campaign Sender",
    "permissions": ["read", "write"],
    "domainScope": "specific",
    "allowedDomainIds": [
      "domain_private_001",
      "domain_shared_002"
    ],
    "defaultDomainId": "domain_shared_002"
  }'

这时：

• 这把 Key 仍然只允许访问勾选的两个域名
• 省略 domain 时，会优先使用 domain_shared_002
• 如果你后续删掉默认域名，系统才会回到“优先私有自有域名”的自动选择逻辑

五、这次升级真正改变了什么

这次升级不是为了把规则搞复杂，而是把几个最容易误解的默认行为重新讲清楚：

• 可访问范围和自动选择逻辑拆开了
• 默认域名变成了一等能力，不再只能靠“随机”
• 省略 domain 时的行为更保守，也更容易预测
• 显式传 domain 的优先级仍然最高，不会破坏已有明确调用

如果你现在已经在用 API Key、域名共享和临时邮箱创建接口，这一版最大的变化不是“能做更多”，而是“默认行为更可控，集成更少踩坑”。