发送邮件

一套 API， 发送你的每一封邮件。

开始使用阅读发送指南
接入方式：

事务性或营销邮件，一条或上百条，都通过同一套 Email API 发送，内置幂等、抑制和 webhook。可传入原始 HTML，也可渲染你的 React Email 模板。

welcome.tsx
200 · 1.2s
import { BirdClient } from "@messagebird/sdk";
import { render } from "@react-email/render";
import { WelcomeEmail } from "./emails/welcome";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const { data, error } = await bird.email.send({
  from:    "Bird <hello@bird.com>",
  to:      ["ada@example.com"],
  subject: "Your invite is ready",
  html:    await render(<WelcomeEmail name="Ada" />),
}).safe();

if (error) throw error;
console.log(data.id);
// → "em_2bX91Yk8h..."

五分钟发出你的第一封邮件。

用你已经在用的语言。

发送是 Bird Email API 的核心。首次发送可以发往经核准的测试地址（delivered@messagebird.dev），让你在验证域名之前就能试用整个平台（发送、webhook、抑制）。

1
2
3
4
5
6
7
8
9
10
import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const { data, error } = await bird.email.send({
  from:    "you@yourdomain.com",
  to:      ["delivered@bird.dev"],
  subject: "Hello from Node",
  html:    "<p>It works.</p>",
}).safe();

五件你无需自己构建的事。

在每个 Bird 渠道上都是同一套契约。

  1. 01

    事务性 + 营销。

    同一个端点既能发送密码重置，也能发送营销活动。由 category 字段决定如何应用抑制和退订。

  2. 02

    模板任你选择。

    传入原始 HTML，或在你的应用中把 React Email 模板渲染成 HTML 后发送结果。无需改动你的工具链。

  3. 03

    批量最多 100 封。

    每次调用最多 100 封独立邮件，各自拥有专属收件人和变量，作为一个整体校验，因此绝不会半途只发出一部分。

  4. 04

    契约层面的幂等。

    每次发送都接受一个幂等键，因此超时后重试的请求会返回原始结果，而不会重复发送。

  5. 05

    每次状态变更都有 webhook。

    已接受、已送达、已打开、已点击、退信、投诉。每一条都经过 HMAC 签名、防重放、幂等，在所有渠道上使用相同的信封格式。

已经在别处发送邮件？一个下午即可完成迁移。

你现有的调用几乎无需改动：换掉客户端，保留你的模板，把 webhook 指向同一个端点。迁移指南涵盖 SendGrid、Amazon SES、Mailgun 和 Resend。

sendgrid.ts
SendGrid
import sgMail from "@sendgrid/mail";

sgMail.setApiKey(process.env.SENDGRID_API_KEY!);

await sgMail.send({
  from:    "hello@bird.com",
  to:      "ada@example.com",
  subject: "Your invite is ready",
  html:    "<p>Welcome aboard, Ada.</p>",
});
bird.ts
Bird
import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

await bird.email.send({
  from:    "hello@bird.com",
  to:      ["ada@example.com"],
  subject: "Your invite is ready",
  html:    "<p>Welcome aboard, Ada.</p>",
});

一条或上百条，一次调用。

在一个请求中批量发送至多 100 条相互独立的消息，每条都有各自的收件人和变量。整批作为一个整体进行校验：只要有一条消息有误，整个调用就会以 422 被拒绝，所以绝不会发出一半。单个幂等键让整个请求可以安全重试。

digest.ts
202 · batch
import { BirdClient } from "@messagebird/sdk";
import { render } from "@react-email/render";
import { Digest } from "./emails/digest";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const messages = await Promise.all(
  users.map(async (u) => ({
    from:    "Bird <hello@bird.com>",
    to:      [u.email],
    subject: "Your weekly digest",
    html:    await render(<Digest user={u} />),
  })),
);

const { data: batch, error } = await bird.email
  .sendBatch(messages, { idempotencyKey: `digest-${runId}` })
  .safe();

if (error) throw error;
console.log(`queued ${batch.data.length} messages`);

为每次发送附带你自己的上下文。

标签是一等的可筛选维度：在 stats API 中按营销活动、模板或实验切分送达和互动数据（每条消息最多 20 个）。元数据是任意 JSON，最多 2 KB，在每次读取和 webhook 中原样往返，让你自己的 ID 随消息一起传递。

tagged.ts
await bird.email.send({
  from:     "Bird <hello@bird.com>",
  to:       ["ada@example.com"],
  subject:  "Your invite is ready",
  html:     "<p>Welcome aboard, Ada.</p>",
  tags:     [{ name: "campaign", value: "spring-2026" }],
  metadata: { user_id: "u_2bX91", order_id: "ord_5512" },
});

全程跟踪每封邮件的完整生命周期。

发送会立即返回 202；结果以每个收件人一条 webhook 的形式送达。验证一次签名，按 type 分支处理：与你已经为 SMS、语音和 WhatsApp 处理的信封格式相同。

app/api/webhooks/bird/route.ts
signed
import { bird } from "@/lib/bird";

export async function POST(req: Request) {
  const event = bird.webhooks.unwrap(
    await req.text(),
    Object.fromEntries(req.headers),
  );

  switch (event.type) {
    case "email.delivered":
      await markDelivered(event.data.email_id);
      break;
    case "email.bounced":
      await flag(event.data.recipient, event.data.bounce_type);
      break;
  }

  return new Response(null, { status: 204 });
}

硬退信、投诉和退订也会自动更新你的抑制列表，这样一个无效地址就不会让你的声誉受到两次损失。

  • email.accepted已被 API 接受并排队等待投递。
  • email.processed已生成并交付给发送管道。
  • email.delivered接收方邮件服务器已接受该邮件。
  • email.deferredBird 会自动重试的临时性失败。
  • email.bounced永久性失败：退信类型和 SMTP 代码包含在负载中。
  • email.opened跟踪像素已加载（仅非预取的打开才计入）。
  • email.clicked一个被跟踪的链接被点击了。
  • email.complained收件人将该邮件举报为垃圾邮件。
  • email.unsubscribed收件人通过邮件正文中被跟踪的链接退订。

上线前测试每一种结果。

在沙箱中，由地址而非你的账户状态决定结果。发往 delivered@messagebird.dev 可得到干净的送达，或发往 bounce@、complaint@ 和 suppressed@ 来通过真实管线和 webhook 触发各条失败路径。无需验证域名，也不会危及你的声誉。生产环境发送会按应有的方式加以限制：你需要先验证域名，新域名或专用 IP 会经过声誉预热逐步提量，之后才承载全量流量。

在文档中深入了解。

阅读发送指南，接入邮件事件和 webhook，或者，如果你从其他服务商迁移而来，按照面向 SendGrid、SES、Mailgun 或 Resend 的迁移指南操作。

发送常见问题

我能同时发送事务性和营销邮件吗？+
可以。两者都通过同一套发送 API；唯一的区别是 category 字段，它决定如何应用抑制和退订。密码重置和收据请选 transactional，营销活动请选 marketing。
你们支持 React Email 模板吗？+
在你的应用中把 React Email 模板渲染为 HTML——@react-email/render 中的 render 函数无需改动即可使用——然后将结果作为 html 正文传入。你的模板工具链无需任何改变。
我在一次请求中能发送多少封邮件？+
每次批量调用最多 100 封独立邮件，各自拥有专属收件人、主题和变量。批次作为一个整体校验，因此只要有一封无效，整个调用就会以 422 被拒绝——绝不会半途只发出一部分。单封邮件可在 to、cc 和 bcc 中包含 1–50 个收件人。
如果请求超时后我重试，会发生什么？+
为每次逻辑发送附带一个 Idempotency-Key。如果原始请求已成功但响应丢失，用相同的 key 重放会返回原始结果（带有 Idempotency-Replay 头标记），而不会再次发送。
速率限制是多少？+
单封发送和批量发送有各自独立的限额——免费档每分钟 10 次单封发送和 5 次批量调用（5 × 100 = 500 封邮件/分钟），到 Growth 档则提升至每分钟 1,000 次发送和 100 次批量调用。限额按请求计数，而非按收件人，因此批量发送才是放大吞吐量的杠杆。
我如何在不发送真实邮件的情况下测试？+
发送到 delivered@messagebird.dev 这样的沙盒地址——结果由地址决定，而非你的账户状态——因此你可以在验证域名之前就演练发送、webhook 和抑制。像 bounce@ 和 complaint@ 这样的地址会通过真实管道模拟相应的结果。

Email 平台的其余功能

一套 API，一组密钥。探索其他能力。

送达率身份验证、IP 预热、抑制和黑名单监控。分析按域名、按 ISP、按 IP 的送达和互动指标。专用 IP托管式专用 IP 及 IP 池，自动预热。发送域名域名验证、DKIM/SPF/DMARC 签名，以及 DMARC 监控。抑制对退信、投诉和退订进行自动且可逆的抑制。群发营销活动：起草、锁定受众、排期并发送。受众你的联系人，以及你在群发中锁定的受众。Email API 概览完整的 Email API：发送、送达率、IP、抑制、分析和群发。

全球约 40% 的商业邮件已经跑在 Bird 上。

在我们已运营十年的基础设施上发送事务性邮件和营销邮件。发送只是 Bird Email API 的能力之一：送达率、专用 IP、抑制和分析随之一同提供。

探索 Email 平台开始使用

从一个渠道开始。
准备好后，再添加其他渠道。

测试 API 密钥即刻可用。添加支付方式并验证发送者身份后，即可解锁生产环境。

立即开始阅读文档

正在使用 Claude Code、Cursor 或 Codex？复制一条设置提示，您的智能代理即可自动安装 Bird CLI 和相关技能。选择您的工具：