authorizing-api-requests

Mailtrap API 请求的授权方式

概述

每个 Mailtrap API 请求都需要两样东西：

1. 请求头中的API 令牌——用于证明身份并携带权限范围。
2. 对于账户范围的端点（大多数不在发送主机下的端点），URL 路径中的 account_id。

本技能是这两项内容的唯一准确信息来源。其他技能（sending-emails、testing-with-sandbox、using-email-templates、managing-contacts、setting-up-sending-domain）会引用这些约定，而不是重复说明。

何时使用

• 在代码、脚本、CI、IaC 或 AI Agent 中编写 Mailtrap API 调用之前
• 选择要配置的令牌权限范围和邮件流
• 决定令牌的存储位置（环境变量、密钥管理器、CI）
• 为账户范围的端点解析 account_id
• 排查 401 Unauthorized / 403 Forbidden 响应

API 令牌

在设置 > API 令牌中创建令牌，并选择可用的最小权限范围：

• Email Sending API——适用于 send.api.mailtrap.io 和 bulk.api.mailtrap.io。尽可能按邮件流（事务性、批量）设置权限范围。
• Email Testing API——适用于 Sandbox（sandbox.api.mailtrap.io）。始终与实时发送令牌分开。
• 账户级 API——适用于 Contacts、Templates、Sending Domains、Suppressions，以及 https://mailtrap.io/api/accounts/{account_id}/... 下的其他端点。

如果用户的套餐支持，单个令牌可以涵盖多个权限范围；但建议使用范围更窄的令牌（一个邮件流 / 一个项目 / 一个产品界面），这样即使发生泄露，影响范围也有限。参考：API 令牌文档。

身份验证请求头（两种等效形式）

Mailtrap 接受任意一种请求头。示例中使用 Bearer，这是更常见的 HTTP 惯例，也与大多数生成的 SDK 代码一致。

形式	请求头	使用场景
Bearer（首选）	Authorization: Bearer $MAILTRAP_API_TOKEN	新代码、SDK、curl 示例的默认形式
Api-Token（旧版）	Api-Token: $MAILTRAP_API_TOKEN	较旧的客户端，或使用 Bearer 不方便的场景

不要同时发送两种请求头。两种请求头中使用的值相同。

令牌的存放位置

• **本地开发：**使用环境变量，或将 .env 文件加入 .gitignore。通过 direnv、dotenv 或框架内置机制加载。
• **CI / 构建：**使用 CI 提供商的加密密钥存储（GitHub Actions secrets、GitLab CI variables、CircleCI contexts）。仅将其注入为环境变量。
• **生产 / 暂存环境：**使用真正的密钥管理器（AWS Secrets Manager、GCP Secret Manager、Azure Key Vault、HashiCorp Vault、Doppler、1Password 等）。按计划轮换。
• **Agent / 大模型工作流：**使用宿主 Agent 的密钥存储。切勿将令牌粘贴到聊天或提示词中。

硬性规则：

• 切勿在源代码、配置或笔记本中硬编码令牌。
• 切勿提交令牌。如果令牌进入了 git，就要轮换；历史记录会永久保留。
• 切勿将令牌作为命令行标志传递——它会泄露到 shell 历史记录、ps 和 CI 日志中。
• 切勿让大模型在生成的代码中回显字面令牌。所有示例都使用 $VAR_NAME shell 变量占位符，让生成的代码读取环境变量，而非使用字面值。
• 切勿混用 Sandbox 和实时令牌。Sandbox 密钥泄露后也不得能够发送真实邮件。

推荐的环境变量名称

这些名称在此存储库中的所有其他技能以及下方的示例片段中保持一致。

变量	用途
MAILTRAP_API_TOKEN	通用 API：邮件发送（事务性和批量）、模板、联系人、发送域、抑制列表
MAILTRAP_SANDBOX_API_TOKEN	沙盒 / 邮件测试（独立范围）
MAILTRAP_ACCOUNT_ID	账户范围端点的路径参数

如果你的环境使用不同的名称，请在启动时统一设置别名，这样其他技能中的示例就能原样使用。

自动解析 account_id

account_id 是每个 https://mailtrap.io/api/accounts/{account_id}/... 端点中的整数前缀。不要将其硬编码。 它会因环境而异，在不同组织中也各不相同；将脚本复制到队友的账户时，还可能在不知情的情况下使用错误值。

每个会话开始时，通过 Accounts 端点解析一次。该端点会列出令牌可访问的所有账户：

curl -s https://mailtrap.io/api/accounts \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN"

响应格式（数组）：

[
  {"id": 12345, "name": "My Company", "access_levels": [1000]},
  {"id": 67890, "name": "Client Account", "access_levels": [100]}
]

access_levels 的取值：

• 1000 — 账户所有者
• 100 — 管理员
• 10 — 查看者（大多数端点仅可读）

用于缓存为环境变量的单行命令（如果令牌可以访问多个账户，请选择正确的账户）：

export MAILTRAP_ACCOUNT_ID=$(curl -s https://mailtrap.io/api/accounts \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" | jq '.[0].id')

参考：Accounts API。

快速参考

# Live sending (no account_id in path)
curl -X POST https://send.api.mailtrap.io/api/send \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

# Account-scoped endpoint
curl "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/lists" \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN"

# Sandbox / Testing
curl -X POST "https://sandbox.api.mailtrap.io/api/send/$MAILTRAP_INBOX_ID" \
  -H "Authorization: Bearer $MAILTRAP_SANDBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

常见错误

错误	修复
在代码、配置或笔记本中硬编码令牌	从 $MAILTRAP_API_TOKEN 加载（环境变量、.env、CI 密钥、密钥管理器）；如果令牌曾经泄露，请轮换令牌
将令牌作为 CLI 标志传递（--token=...）	使用环境变量；CLI 标志会泄露到 Shell 历史记录、ps 和 CI 日志中
提交令牌后，又在之后的提交中将其删除	历史记录会永久保留该值 — 立即轮换令牌，不要只删除文件
将令牌粘贴到聊天 / 提示词 / 问题中	将聊天视为公开场合；如果发生过这种情况，请轮换令牌
使用正式环境的 MAILTRAP_API_TOKEN 访问沙盒主机	沙盒有独立范围，并使用 MAILTRAP_SANDBOX_API_TOKEN；混用会导致请求失败，或意外发送真实邮件
硬编码 account_id	每次运行时通过 GET https://mailtrap.io/api/accounts 解析一次，并通过 $MAILTRAP_ACCOUNT_ID 传递
令牌可以访问多个账户时选错账户	根据 name 或 access_levels（1000 = 所有者）筛选 GET /api/accounts 响应，而不是使用 .[0]
同时发送 Authorization 和 Api-Token 标头	任选其一（新代码使用 Bearer）；重复发送没有必要，还会让某些中间件困惑
使用查看者权限范围的令牌执行写入操作	检查 access_levels；对相关账户执行写入操作需要 100（管理员）或 1000（所有者）