发送邮件

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

开始使用阅读发送指南

接入方式：

CursorCopied!

事务性或营销邮件，一条或上百条，都通过同一套 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..."

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、抑制）。

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  subject: "Hello from Bird",
  html: "<p>My first Bird email.</p>",
});
console.log(msg.id, msg.status); // "em_…", "accepted"

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

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

01
事务性 + 营销。
同一个端点既能发送密码重置，也能发送营销活动。由 category 字段决定如何应用抑制和退订。
02
模板任你选择。
您可以直接传入原始 HTML，也可以在应用中将 React Email 模板渲染为 HTML 后发送结果，或者指定一个已存储的模板由我们为您渲染。您的工具链无需改变。
03
批量最多 100 封。
每次调用最多 100 封独立邮件，各自拥有专属收件人和变量，作为一个整体校验，因此绝不会半途只发出一部分。
04
契约层面的幂等。
每次发送都接受一个幂等键，因此超时后重试的请求会返回原始结果，而不会重复发送。
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@yourdomain.com",
  to:      "delivered@messagebird.dev",
  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@yourdomain.com",
  to:      ["delivered@messagebird.dev"],
  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:    "Acme <hello@yourdomain.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:     "Acme <hello@yourdomain.com>",
  to:       ["delivered@messagebird.dev"],
  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发送已被接受，正在准备投递。
email.processed已排队等待收件人邮件服务器处理。
email.delivered收件人邮件服务器已接受该消息。
email.deferred暂时被拒绝，我们将进行重试。
email.bounced永久失败：负载中包含退信类型和 SMTP 代码。
email.opened收件人打开了邮件。可能触发多次。
email.clicked收件人点击了跟踪链接。
email.complained收件人将该邮件举报为垃圾邮件。
email.unsubscribed收件人通过跟踪的退订链接选择了退出。

上线前测试每一种结果。

在沙盒环境中，收件人地址决定了结果，无需依赖您的账户状态。发送至 delivered@messagebird.dev 可获得正常投递，也可以发送至 bounce@、softbounce@、deferred@、complaint@ 和 suppressed@ 来驱动各种失败路径，经过真实的处理流程和真实的 Webhook。无需验证域名，也不会影响您的发送信誉。生产环境设有门控机制：您需要先验证域名，新域名或专用 IP 会在承载全量流量之前经历预热过程。

在文档中深入了解。

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

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， 发送你的每一封邮件。