sending-emails

发送电子邮件（Mailtrap）

概览

Mailtrap 通过 Email API（REST）或 SMTP 发送实时电子邮件。API/SMTP 支持两种 流：Transactional（非促销类，由应用生成）和 Bulk（促销类／营销邮件量）。Batch 不是第三种流：它表示如何在与内容相匹配的流上一次请求提交多封邮件。Campaigns 是面向 Mailtrap 联系人发送促销邮件的独立产品路径。集成开发或排错（包括 AI 辅助编码）时，请结合阅读Transactional／Bulk 开发者页面。

集成方式（优先顺序）

优先顺序：

1. 适用于用户平台的插件或集成（无需代码或只需少量配置）（如有）
2. 适用于你所用语言的官方 SDK（如有；维护良好的客户端、类型化辅助工具，可减少 URL／身份验证错误）。
3. HTTP Email API（没有适用的 SDK，或 SDK 不合适时；直接向 /api/send 或 /api/batch 发送带 JSON 的 POST 请求）。
4. 仅在确实需要时使用 SMTP（旧版技术栈、仅支持 SMTP 的主机／平台，或排除 HTTP 的硬性限制）。

选择发送方式

方式	适用场景
Transactional，单封邮件	由应用生成的电子邮件（密码重置、收据、通知、提醒）。每个 POST https://send.api.mailtrap.io/api/send 请求发送一封逻辑邮件
Bulk	向由你自行管理的联系人发送促销邮件，并通过 Mailtrap 批量发送。它与“batch”不同：bulk 指的是流，而不是 batch 端点。
Batch	你需要同时提交多封不同的邮件（每个请求最多 500 封）。可减少 HTTP 开销；transactional 和 bulk 均可使用
Campaigns	向存储为 Mailtrap 联系人的收件人发送促销邮件，使用 Mailtrap Campaigns（产品中的受众群体、定时发送和报告）。建议使用此方式，以免自行实现联系人管理和邮件发送逻辑；发送流程开始前需要在 UI 中完成设置——此技能不能替代该工作流。

**生成 SDK 代码前：**请阅读下方 SDKs 部分中相关 SDK 仓库的 README，确认当前的方法签名、构造函数选项和示例。不要依赖记忆。

相关技能：authorizing-api-requests（令牌、环境变量、身份验证标头）、using-email-templates（模板 UUID 和变量）、testing-with-sandbox（安全测试）、setting-up-sending-domain（发送前验证）。

不适用场景

• 仅用于沙盒——捕获邮件但不实际发送，或在沙盒中读取邮件（testing-with-sandbox）。
• 主要需求是Webhook、Campaigns 界面的分步设置或深入了解送达能力。
• 完整的 API 参考——确定用户的操作路径后，链接到官方发送文档，查看完整的架构、可选字段和边缘情况。

快速参考

Email API

流类型	发送端点	批量发送端点	授权标头
事务型邮件	POST https://send.api.mailtrap.io/api/send	POST https://send.api.mailtrap.io/api/batch	Authorization: Bearer $MAILTRAP_API_TOKEN
批量（促销 / 营销邮件量）	POST https://bulk.api.mailtrap.io/api/send	POST https://bulk.api.mailtrap.io/api/batch	Authorization: Bearer $MAILTRAP_API_TOKEN

SMTP

设置	事务型邮件	批量邮件
主机	live.smtp.mailtrap.io	bulk.smtp.mailtrap.io
端口	587（也支持 25、2525、465，使用 SSL）	587（也支持 25、2525、465，使用 SSL）
用户名	api	api
密码	API 令牌（$MAILTRAP_API_TOKEN）	API 令牌（$MAILTRAP_API_TOKEN）

令牌

在 Authorization: Bearer ... 或 Api-Token: ... 中使用 $MAILTRAP_API_TOKEN。只要令牌的作用域包含对应流，同一个令牌就可用于 send.api.mailtrap.io 和 bulk.api.mailtrap.io。完整指南（作用域、存储、轮换）请参阅技能 authorizing-api-requests。

速率限制

作用域	限制	时间窗口
发送 API（每个令牌）	150 个请求	10 秒

遇到 429 时，请使用退避策略。

JSON 请求体（非模板）

常见字段包括 from、to、subject 和 text 和／或 html。可选字段：category、custom_variables。准确的请求体请参阅：事务型邮件发送和批量邮件发送。

示例（curl）

发送事务型邮件（send.api.mailtrap.io）：

curl -X POST https://send.api.mailtrap.io/api/send \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]", "name": "Your App"},
    "to": [{"email": "[email protected]"}],
    "subject": "Hello",
    "text": "Plain text body"
  }'

批量流在批量主机上使用相同的路径和 JSON 结构（使用相同的环境变量；令牌只需包含批量流作用域）：

curl -X POST https://bulk.api.mailtrap.io/api/send \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]", "name": "Your App"},
    "to": [{"email": "[email protected]"}],
    "subject": "Promotional",
    "html": "<p>HTML body</p>"
  }'

批量发送（消息数组；每个请求最多 500 条——完整架构请参阅 API 文档）：

curl -X POST https://send.api.mailtrap.io/api/batch \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"from":{"email":"[email protected]"},"to":[{"email":"[email protected]"}],"subject":"One","text":"..."}]}'

JSON 请求体（模板）

使用 Mailtrap 托管的模板时，请使用 template_uuid 和 template_variables，而不要使用原始的 text／html。最简示例：

curl -X POST https://send.api.mailtrap.io/api/send \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]", "name": "Your App"},
    "to": [{"email": "[email protected]"}],
    "template_uuid": "your-template-uuid",
    "template_variables": {"user_name": "Jane"}
  }'

请参阅技能 using-email-templates，以及与非模板发送相同的 API 操作。

SDK

• Node.js
• Python
• PHP
• Ruby
• Java
• .NET
• CLI

抑制名单

Mailtrap 会自动管理硬退信、举报为垃圾邮件或取消订阅的地址对应的抑制名单，并且不会再次向这些被抑制的收件人发送邮件。详情请参阅抑制名单文档。

常见错误

错误	修正
混淆 batch 和 bulk	Batch = 在一个 /api/batch 请求中发送多条消息。Bulk = 推广邮件流/主机和令牌
在事务邮件主机上使用推广邮件 API	对于代码生成的推广内容，请使用 bulk 基础 URL 和 bulk 令牌
在 send.api.mailtrap.io 上发送 bulk 流量	推广/bulk 邮件流使用 bulk.api.mailtrap.io
使用沙盒 SMTP 主机发送正式邮件	正式发送使用 live.smtp.mailtrap.io 或 bulk.smtp.mailtrap.io
SMTP 用户名是电子邮件地址	用户名是 api；密码是 API 令牌
域名验证前就开始发送	完成 Sending Domains 设置和合规流程（参见 setting-up-sending-domain）
凭记忆猜测 SDK API	阅读 SDK README 和 OpenAPI 链接的示例；不要臆造构造函数或方法名称
全新应用优先选择 SMTP	如果有 平台集成，优先使用它，然后是 SDK，再然后是 HTTP API；仅在必要时使用 SMTP（参见 如何集成）