Mailtrap Sending Emails

发送邮件（Mailtrap）

概述

Mailtrap 通过 Email API（REST）或 SMTP 发送实际邮件。API/SMTP 适用两种 流（stream）：Transactional（非推广、应用生成的邮件）和 Bulk（推广 / 营销大批量邮件）。Batch 不是第三种流：它是在匹配内容的流上用一个请求提交多条消息的方式。Campaigns 是向 Mailtrap 联系人发送推广邮件的独立产品路径。在构建或调试集成（包括 AI 辅助编码）时，请将本文档与 Transactional / Bulk 开发者页面配合使用。

使用时机

在集成、配置或排查 Mailtrap 实际邮件发送时使用，涵盖 Email API、SMTP、事务流、批量流或批次请求。

集成方式（优先顺序）

推荐顺序：

1. 用户平台的插件或集成（零代码或最小配置）在可用的情况下
2. 官方 SDK，当你的语言有官方 SDK 时（维护良好的客户端、类型化辅助、减少 URL/认证出错的可能性）。
3. HTTP Email API，当没有 SDK 或 SDK 不适用时（直接 POST 到 /api/send 或 /api/batch，使用 JSON）。
4. SMTP，仅当你确实需要时（遗留技术栈、只支持 SMTP 的主机/平台，或排除了 HTTP 的硬性约束）。

选择发送方式

**生成 SDK 代码之前：**阅读下方 SDKs 章节中链接的相关 SDK 仓库的 README，了解当前的方法签名、构造函数选项和示例。不要凭记忆猜测。

关联技能：mailtrap-testing-with-sandbox（安全测试）和 mailtrap-setting-up-sending-domain（发送前验证）。

不适用场景

• 仅 Sandbox——捕获邮件但不投递，在沙盒中读取消息（mailtrap-testing-with-sandbox）。
• 主要需求是 webhooks、Campaigns UI 分步设置或送达率深入分析。
• 详尽的 API 参考——当用户路径明确后，链接官方发送文档获取完整 schema、可选字段和边缘情况。

快速参考

Email API

SMTP

Token

在 Authorization: Bearer ... 或 Api-Token: ... 中使用 $MAILTRAP_API_TOKEN。只要 token 的范围覆盖了对应流，同一个 token 可以同时用于 send.api.mailtrap.io 和 bulk.api.mailtrap.io。将 token 存储在环境变量或密钥管理器中，并在访问权限变更时轮换。

速率限制

遇到 429 时使用退避策略。

JSON 请求体（非模板）

典型字段包括 from、to、subject，以及 text 和/或 html。可选字段：category、custom_variables。完整请求体参见：Transactional send 和 Bulk send。

示例（curl）

Transactional 发送（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": "hello@yourdomain.com", "name": "Your App"},
    "to": [{"email": "user@example.com"}],
    "subject": "Hello",
    "text": "Plain text body"
  }'

Bulk 流在 bulk 主机上使用相同的路径和 JSON 结构（相同的环境变量；token 只需要 bulk-stream 范围）：

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

Batch（消息数组；每次请求最多 500 条——完整 schema 参见 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":"a@example.com"},"to":[{"email":"b@example.com"}],"subject":"One","text":"..."}]}'

JSON 请求体（模板）

使用 template_uuid 和 template_variables 替代原始 text/html，以使用 Mailtrap 托管的模板。最小示例：

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

使用与非模板发送相同的 API 操作。

SDK

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

抑制（Suppressions）

Mailtrap 自动管理硬退信、垃圾邮件举报或取消订阅的地址的抑制列表，不会再次向这些被抑制的收件人发送邮件。详情参见 Suppressions 文档。

常见错误

限制

• 本技能概述了 Mailtrap 发送方式的选择；完整 schema 和产品限制请使用 Mailtrap 当前 API 文档。