授权和访问区域

site-search,starlight-theme-select{display:none!important}

导航

指南

方法API

通过链接登录

您的服务器使用 X-API-Key 和 X-Customer-ID 调用 POST /v1/auth/login-link。设置 mailbox_id 可仅打开该邮箱；省略此字段则打开整个账户。locale 用于选择界面语言。

响应包含 login_url、expires_in=300、expires_at（UTC）、account_id 和 mailbox_id。“打开邮箱”按钮应打开完整的 login_url，包括 #token。链接有效期为 5 分钟且只能使用一次。请勿将其写入日志，也不要在浏览器中暴露 API 密钥。

登录页面从地址栏移除令牌，并将其换为 HttpOnly Cookie。若失败或过期，请创建新链接。系统会重新检查访问范围及账户和邮箱状态。用户会话不能创建登录链接。

curl https://adapt-mail.com/v1/auth/login-link \
  -H "X-API-Key: <mail-api-key>" \
  -H "X-Customer-ID: <mail-account-id>" \
  -H "Content-Type: application/json" \
  --data '{"mailbox_id":42,"locale":"en"}'

{
  "login_url": "https://adapt-mail.com/auth/#token=<one-time-token>",
  "expires_in": 300,
  "expires_at": "2026-10-20T12:05:00Z",
  "account_id": 123,
  "mailbox_id": 42
}

合作伙伴密钥

使用集成的邮件 API-key。将其传递给邮件帐户的 X-API-Key 和 ID - 在所需的标头 X-Customer-ID. 中，这是帐户的 ID，而不是邮箱的 external_id 也不是 ID。该密钥仅允许访问您的集成的客户端。

将密钥存储在您合作伙伴的服务器上。请勿将共享集成密钥放置在浏览器或移动应用程序中。

curl 'https://adapt-mail.com/v1/mailboxes' \
  -H 'X-API-Key: <mail-api-key>' \
  -H 'X-Customer-ID: <mail-account-id>'

用户令牌

POST /v1/auth/token 接受 login、password 和 mode. 对于 mode=account，使用登录名 user-ID，对于 mode=mailbox，使用完整邮箱地址。帐号和邮箱密码是独立的。

响应包含 access_token、token_type=Bearer 和 expires_in=3600. 帐户令牌打开其盒子；盒子代币 - 只有一个盒子。过期后，您将收到一个新的令牌。

POST /v1/auth/token
Content-Type: application/json

{"login":"user-123","password":"<password>","mode":"account"}

GET /v1/mailboxes
Authorization: Bearer <access_token>

浏览器会话

POST /v1/auth/login 用于其自己的站点 adapt-mail.com. 它需要正确的 Origin 并安装 HttpOnly cookies. 未分类 X-Mail-Session 选择已保存的输入之一，但没有 cookie 则不会授予访问权限。

对于第三方前端，请使用您的服务器和用户令牌。不要指望来自 cookie: public CORS 的任何站点的随机跨域访问。