你的应用程序向 HTTP 端点发送结构化数据，并收到包含消息结果或错误的响应。这一请求和响应就是电子邮件 API 的工作界面。
电子邮件 API 处理什么？
发送端点接受收件人、主题以及纯文本或 HTML 内容。当提供商支持时，它还可以接受请求头、标签、模板和附件。
事件端点或 webhook 报告接受后发生的情况。常见事件包括投递、退信、投诉、打开和点击。接收 API 将入站邮件转换为结构化消息供你的应用程序使用，而不需要你轮询邮箱。
电子邮件 API 与 SMTP 有什么区别？
SMTP 要求你的应用程序打开连接、进行身份验证、发送命令并读取回复码。电子邮件 API 改用 HTTP 请求，因此客户端库可以处理连接复用、JSON 编码、重试和响应解析。
当你的应用程序已经在使用 HTTP、需要结构化事件，或运行在不方便建立 SMTP 连接的环境中时，选择 API。当现有邮件库或邮件服务器已支持 SMTP 时，选择 SMTP 中继。两种方式可以投递相同的邮件。
| 任务 | 发送 API | SMTP 中继 | 邮箱 API |
|---|---|---|---|
| 发送消息 | 是 | 是 | 回复或撰写 |
| 接收解析后的邮件 | 部分提供商 | 否 | 是 |
| 读取会话历史 | 部分提供商 | 否 | 是 |
| 查看投递情况 | 事件或 webhook | 回复码加事件 | 消息状态和事件 |
不同产品使用电子邮件 API 一词表示不同的功能集。在假设一个 API 覆盖所有行之前，请先查看提供商的 schema。
API 请求应包含什么？
发送提供商要求的字段。记录返回的消息标识符。当重试不能产生重复发送时，保留你自己的幂等键。发送前验证收件人。将密钥保存在服务器端。
一个示例事务性请求包含 from、to、subject、text、category: transactional 以及保存在服务器端的幂等键。发送之前请使用已验证的发送域名。
HTTP 响应表示服务已接受该请求。投递、退信和投诉事件会在之后到达，因此已接受的响应不代表邮件已到达收件箱。
使用 webhook 获取后续事件，而不是将已接受的请求视为邮件到达收件箱的证据。投递和投诉事件描述接受之后发生的情况。
如何使用 Bird 发送？
使用你的工作区 API 密钥、发件人、收件人、内容和可选元数据调用 Bird 的 createEmailMessage API。邮件发送指南展示了请求和响应字段。
对于回复和入站邮件，创建一个邮箱并消费其消息和投递事件。邮箱指南涵盖了这些端点和 webhook 名称。
总结
- 电子邮件 API 通过 HTTP 提供发送和消息事件。
- 响应确认的是 API 已接受，而非邮件到达收件箱。
- 幂等键使安全的重试成为可能。
- Bird 提供发送和邮箱 API，并为每条路径提供指南。