UnifyPort iconUnifyPort
简体中文
English简体中文
  • 作者： Anonymous
  • 10 分钟阅读

电子邮件 API 集成：开发者完整指南

了解电子邮件 API 集成的工作原理，比较 REST 与 SMTP，探索代码示例、关键功能、定价模式，以及如何选择合适的提供商。

电子邮件 API 集成：开发者完整指南

电子邮件 API 集成是将您的应用程序连接到电子邮件服务提供商的应用程序编程接口的过程，以便您可以通过编程方式发送、接收和跟踪电子邮件。无需管理自己的邮件服务器、配置 SMTP 中继以及处理送达率问题，您只需调用 REST 端点或使用提供商 SDK，让平台处理基础设施。

本指南涵盖电子邮件 API 集成的工作原理、REST API 与 SMTP 中继之间的区别、选择提供商时需要注意的事项、实用代码示例，以及电子邮件如何融入更广泛的多渠道消息传递策略。

什么是电子邮件 API？

电子邮件 API 集成：开发者完整指南 - 什么是电子邮件 API？

电子邮件 API 集成：开发者完整指南 - 什么是电子邮件 API？.

电子邮件 API 集成：开发者完整指南 - 什么是电子邮件 API？。

电子邮件 API 是一组 HTTP 端点，允许开发者直接从代码发送事务性或营销电子邮件。您使用 API 密钥进行身份验证，构建包含发件人、收件人、主题和正文的请求，提供商将排队并投递消息。

大多数现代电子邮件 API 提供：

  • 发送端点，用于发送单个或批量电子邮件
  • 模板端点，用于管理可重用的 HTML 设计
  • Webhook 事件，用于投递状态、打开、点击和退信
  • 分析端点，用于查询性能数据
  • 抑制列表端点，用于管理退订和退信

与传统的 SMTP（一种用于服务器之间邮件传输的低级协议）不同，电子邮件 API 是更高级别的抽象，在一个接口中包含身份验证、模板、跟踪和事件流。

REST API 与 SMTP 中继：应该使用哪个？

电子邮件 API 集成：开发者完整指南 - REST API 与 SMTP 中继：应该使用哪个？

电子邮件 API 集成：开发者完整指南 - REST API 与 SMTP 中继：应该使用哪个？.

电子邮件 API 集成：开发者完整指南 - REST API 与 SMTP 中继：应该使用哪个？。

两种方法都可以发送电子邮件，但它们解决不同的问题。

因素 REST API SMTP 中继
设置复杂度 低；一个端点和 API 密钥 较高；需要 SMTP 客户端配置
功能访问 完整：模板、分析、Webhook 有限；主要仅发送
错误处理 结构化 JSON 响应 SMTP 状态代码
语言支持 流行语言的 SDK 任何具有 SMTP 库的语言
最适合 事务性和事件驱动的电子邮件 遗留应用和简单发送

如果您正在构建新应用程序，REST 电子邮件 API 几乎总是更好的选择。您获得结构化响应、更丰富的元数据，以及动态模板和实时事件 Webhook 等功能。当您迁移已经使用 SMTP 的遗留系统，或者需要快速替换现有邮件服务器时，SMTP 中继才有意义。

电子邮件 API 集成如何工作

电子邮件 API 集成：开发者完整指南 - 电子邮件 API 集成如何工作

电子邮件 API 集成：开发者完整指南 - 电子邮件 API 集成如何工作.

电子邮件 API 集成：开发者完整指南 - 电子邮件 API 集成如何工作。

典型的集成遵循以下流程：

  1. 创建账户并获取 API 密钥。 该密钥用于验证您的请求，应存储在环境变量中，切勿放在源代码中。
  2. 验证您的发送域名。 您添加 SPF 和 DKIM DNS 记录，以便邮箱提供商信任您的邮件。
  3. 发送您的第一个请求。 您调用发送端点，包含发件人、收件人、主题以及 HTML 或纯文本正文。
  4. 处理 Webhook。 当电子邮件被投递、打开、点击或退信时，提供商会向您的服务器发送 HTTP 回调。
  5. 监控和迭代。 您使用提供商的仪表板或 API 跟踪送达率并调整发送实践。

以下是使用 Resend 的 Node.js SDK 的最小示例：

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

await resend.emails.send({
  from: 'Acme <onboarding@resend.dev>',
  to: ['customer@example.com'],
  subject: 'Your account is ready',
  html: '<p>Welcome aboard!</p>',
});

以及使用 SendGrid 的 Python 库的相同概念：

import os
from sendgrid import SendGridAPIClient
from sendgrid.helpers.mail import Mail

message = Mail(
    from_email='noreply@example.com',
    to_emails='customer@example.com',
    subject='Password reset',
    html_content='<strong>Click here to reset your password</strong>'
)

try:
    sg = SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
    response = sg.send(message)
    print(response.status_code)
except Exception as e:
    print(e)

两个示例都展示了相同的模式：使用密钥进行身份验证，构建消息对象，调用发送方法，并处理响应。

评估电子邮件 API 的关键功能

电子邮件 API 集成：开发者完整指南 - 评估电子邮件 API 的关键功能

电子邮件 API 集成：开发者完整指南 - 评估电子邮件 API 的关键功能.

电子邮件 API 集成：开发者完整指南 - 评估电子邮件 API 的关键功能。

并非所有电子邮件 API 都相同。在比较提供商时，重点关注直接影响送达率、可靠性和开发者体验的功能。

送达率基础设施

送达率是最重要的因素。寻找提供专用 IP 选项、自动 SPF/DKIM/DMARC 设置、退信处理以及发件人声誉管理的提供商。例如，SendGrid 报告其基础设施的平均投递率为 99.5%，收件箱放置率为 91.3%。

Webhook 和事件跟踪

实时 Webhook 让您在自己的系统中响应电子邮件事件。您可以在有人打开邮件时触发后续操作，在有人点击链接时标记潜在客户，或在退信后抑制后续发送。Mailjet、SendGrid 和 Resend 都提供投递、打开、点击、退信和垃圾邮件投诉的 Webhook 事件。

幂等性和重试

网络故障时有发生。幂等键确保重试请求不会导致重复电子邮件。Resend 支持发送请求上的幂等键，这在您的应用程序具有自动重试逻辑时至关重要：

await resend.emails.send(
  {
    from: 'Acme <onboarding@resend.dev>',
    to: ['customer@example.com'],
    subject: 'Welcome',
    html: '<p>Hello!</p>',
  },
  {
    idempotencyKey: 'welcome-user/123456789',
  }
);

安全性和合规性

电子邮件通常携带敏感数据。检查传输中的 TLS 加密、SOC 2 合规性、GDPR 一致性以及区域数据驻留选项。例如，Mailjet 提供基于欧盟的数据中心和 ISO 27001 认证，以满足欧洲合规要求。

SDK 和文档质量

强大的 SDK 可将集成时间从几天缩短到几小时。寻找您主要语言的官方库——Node.js、Python、PHP、Go、Ruby、Java 和 C# 是常见的——以及清晰、交互式且带有真实代码示例的文档。

定价模式：按量计费与按联系人计费

电子邮件 API 定价通常分为两类：

  • 按量计费：您按月发送的电子邮件数量付费。Mailjet 使用此模式，在更高层级包含无限联系人。这使您的成本在列表增长时保持可预测。
  • 按联系人计费：您根据数据库中的唯一联系人数量付费，无论发送多少封电子邮件。如果您维护大量列表但发送频率低，这可能会变得昂贵。

大多数提供商提供免费层级用于测试。SendGrid 提供每天 100 封电子邮件，持续 60 天，而 Resend 和 Mailjet 有免费月度配额。从免费层级开始，验证您的集成，然后根据预计的月发送量选择付费计划。

电子邮件 API 与多渠道消息 API

电子邮件很少是您的应用程序唯一需要的渠道。现代产品通过电子邮件发送密码重置，通过短信发送订单确认，通过 WhatsApp 发送支持消息，以及通过推送发送参与通知。为每个渠道构建单独的集成会成倍增加您的工程开销。

这就是统一消息 API 的用武之地。无需为电子邮件维护一个集成，为短信维护另一个，为聊天平台维护第三个，您只需连接一次到一个平台，该平台将所有渠道标准化为单个 REST API 和标准化 Webhook 事件。

UnifyPort 对 Telegram、WhatsApp、LINE、X（Twitter）、Zalo 和 TikTok 等消息渠道采取这种方法。它抽象了提供商特定的 SDK 和差异，为消息投递和事件摄取提供标准化接口。对于已经管理多个消息集成的团队，这种模式——一个 API、一种事件格式、一个 Webhook 控制平面——可以显著降低集成和维护成本。

同样的架构逻辑适用于电子邮件。如果您的应用程序发送事务性电子邮件以及跨多个聊天平台的消息，请评估统一消息层是否可以整合您的基础设施。要深入了解多渠道消息如何融入您的 CRM，请参阅本指南：CRM 消息集成。

常见的电子邮件 API 集成挑战

身份验证和密钥管理

API 密钥授予对您发送能力的完全访问权限。将它们存储在环境变量或密钥管理器中，定期轮换，切勿提交到版本控制。大多数提供商允许您创建具有不同权限的多个密钥，用于开发、暂存和生产。

域名验证

从未验证的域名发送几乎保证进入垃圾邮件文件夹。在发送任何生产电子邮件之前设置 SPF、DKIM 和 DMARC 记录。此过程通常需要 15-30 分钟，并且每个域名只需设置一次。

Webhook 可靠性

Webhook 只有在您的端点可靠时才有用。实现重试逻辑，验证 Webhook 签名，并异步处理事件，以便慢速处理程序不会阻塞传入回调。大多数提供商在 24-72 小时内重试失败的 Webhook。

速率限制

电子邮件 API 实施速率限制以保护其基础设施。了解您的提供商的限制，并为高容量发送实施客户端节流或排队。批量端点有助于发送到大型收件人列表。

电子邮件 API 集成检查清单

在您上线之前，请完成此检查清单：

  1. 使用 SPF、DKIM 和 DMARC 验证您的发送域名
  2. 安全存储 API 密钥，在环境变量或密钥管理器中
  3. 为所有发送请求实现幂等键
  4. 设置 Webhook 处理，用于退信、投诉和投递事件
  5. 添加重试逻辑，对瞬时故障使用指数退避
  6. 从第一天开始监控送达率指标
  7. 在生产流量之前使用沙盒或免费层级进行测试
  8. 记录您的集成，以供未来的维护者使用

相关阅读

来源和进一步阅读

常见问题解答

电子邮件 API 和 SMTP 有什么区别？

电子邮件 API 是一个 RESTful 接口，在一个包中包含身份验证、模板、跟踪和事件 Webhook。SMTP 是用于在服务器之间传输邮件的较低级协议。API 提供更丰富的功能和结构化响应；SMTP 更简单，但仅限于基本发送。

电子邮件 API 集成需要多长时间？

使用现代提供商和官方 SDK，基本集成可以在不到一小时内完成。域名验证增加 15-30 分钟，完整的生产就绪——包括 Webhook、重试和监控——通常需要一到两天。

我需要专用 IP 来发送电子邮件 API 吗？

最初不需要。共享 IP 池对大多数发件人来说效果很好。当您发送高容量（通常每月 100,000 封以上）并希望完全控制发件人声誉时，专用 IP 变得有价值。

我可以将电子邮件 API 用于营销活动吗？

可以。许多提供商，包括 Mailjet 和 SendGrid，通过同一个 API 支持事务性和营销电子邮件。您可以在事务性发送旁边管理模板、细分和活动分析。

如果我的 Webhook 端点宕机会发生什么？

大多数提供商在 24-72 小时内使用指数退避重试失败的 Webhook。除非您的端点在重试窗口内一直宕机，否则事件不会丢失。实施监控，以便在 Webhook 开始失败时收到警报。

电子邮件 API 集成与统一消息 API 相比如何？

电子邮件 API 处理一个渠道。像 UnifyPort 这样的统一消息 API 通过单个 REST API 和标准化 Webhook 事件处理多个消息渠道——Telegram、WhatsApp、LINE、X、Zalo 和 TikTok。如果您的应用程序需要电子邮件和多渠道消息，您可以并排运行电子邮件 API 和统一消息层，而不是为每个渠道构建单独的集成。

结论

对于大多数应用程序来说，电子邮件 API 集成是一个已解决的问题。现代提供商提供 REST 端点、官方 SDK、Webhook 事件和送达率基础设施，这些在内部构建需要数月时间。关键决策是为您的发送量和合规需求选择合适的提供商，正确实现幂等性和重试，并将送达率视为持续实践而非一次性设置。

如果您的消息需求超出电子邮件，扩展到聊天平台和社交渠道，请考虑统一消息 API 是否可以减少您的总集成面。有关统一 API 工作流的实际示例，请参阅 Unipile 示例：真实 API 工作流和代码示例，并了解统一消息平台与传统提供商的比较，请查看 什么是 SMS API 以及如何选择。