authorizing-api-requests

用途

本技能是 Mailtrap API 请求认证与授权的统一参考，适用于在编写任何 Mailtrap API 调用之前（代码、脚本、CI、IaC 或 AI 智能体），以及选择令牌作用域与流、决定令牌存储位置、解析账户级端点的 account_id、排查 401 Unauthorized / 403 Forbidden 响应等场景。其他技能（sending-emails、testing-with-sandbox、using-email-templates、managing-contacts、setting-up-sending-domain）引用这些约定，而不重复定义。

主要能力

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

认证头中的 API 令牌——证明身份并携带作用域。
对于账户级端点（发送主机之外的大多数端点），URL 路径中的 account_id。

API 令牌

在 Settings > API Tokens 创建令牌，使用能正常工作的最小作用域：

Email Sending API——用于 send.api.mailtrap.io 和 bulk.api.mailtrap.io。尽可能按流（transactional、bulk）划分作用域。
Email Testing API——用于 Sandbox（sandbox.api.mailtrap.io）。始终与实时发送令牌分开。
Account-level API——用于 Contacts、Templates、Sending Domains、Suppressions 以及 https://mailtrap.io/api/accounts/{account_id}/... 下的其他端点。

如果用户拥有合适的套餐，单个令牌可以覆盖多个作用域；但优先使用更窄的令牌（一个流 / 一个项目 / 一个产品面），以便泄露时影响范围有限。参考：API tokens 文档。

认证头（两种等价形式）

Mailtrap 接受以下任一头部。示例中使用 Bearer——它是更常见的 HTTP 约定，也匹配大多数生成的 SDK 代码。

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

不要同时发送两者。同一个值放入任一头部即可。

令牌存放位置

本地开发：环境变量，或位于 .gitignore 中的 .env 文件。使用 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 等）。按计划轮换。
智能体 / LLM 工作流：宿主智能体的密钥存储。切勿将令牌粘贴到聊天或提示词中。

硬性规则：

切勿在源代码、配置或笔记本中硬编码令牌。
切勿提交令牌。如果落入 git，请轮换它；历史记录会永久保留。
切勿通过命令行标志传递令牌——它会泄露到 shell 历史、ps 和 CI 日志中。
切勿让 LLM 将字面令牌回显到生成的代码中。在所有示例中使用 $VAR_NAME 形式的 shell 变量占位符，使生成的代码引用环境变量而非字面值。
切勿混用沙箱和实时令牌。泄露的沙箱密钥必须无法发送真实邮件。

变量	用途
MAILTRAP_API_TOKEN	通用 API：Email Send（transactional 和 bulk）、Templates、Contacts、Sending Domains、Suppressions
MAILTRAP_SANDBOX_API_TOKEN	Sandbox / Email Testing（独立作用域）
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。

使用方式（快速参考）

# 实时发送（路径中无 account_id）
curl -X POST https://send.api.mailtrap.io/api/send \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

# 账户级端点
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、.env、CI secret、secret manager）；如果曾泄露则轮换令牌
通过 CLI 标志传递令牌（--token=...）	使用环境变量；CLI 标志会泄露到 shell 历史、ps 和 CI 日志
提交令牌后在后续提交中删除	历史会永久保留该值——立即轮换令牌，不要只是删除文件
将令牌粘贴到聊天 / 提示词 / issue	将聊天视为公开；如果发生则轮换
对沙箱主机使用实时 MAILTRAP_API_TOKEN	沙箱使用自己的作用域和 MAILTRAP_SANDBOX_API_TOKEN；混用要么失败，要么意外发送真实邮件
硬编码 account_id	每次运行通过 GET https://mailtrap.io/api/accounts 解析一次，并通过 $MAILTRAP_ACCOUNT_ID 传递
当令牌能看到多个账户时选错账户	按名称或 access_levels（1000 = owner）过滤 GET /api/accounts 响应，而不是用 .[0]
同时发送 Authorization 和 Api-Token 头部	选择其一（新代码用 Bearer）；重复没有必要，且会混淆某些中间层
使用查看者作用域的令牌进行写入	检查 access_levels；写入需要相关账户的 100（admin）或 1000（owner）

适用场景

在编写任何 Mailtrap API 调用之前（代码、脚本、CI、IaC 或 AI 智能体）。
选择要配置的令牌作用域与流。
决定令牌存放位置（env、secret manager、CI）。
解析账户级端点的 account_id。
排查 401 Unauthorized / 403 Forbidden 响应。

限制

资料未提供关于速率限制、令牌有效期、具体套餐价格或各端点详细参数的信息，暂未提供。

技能介绍

用途