Sign inGet Started

发送您的第一封电子邮件

创建 API 密钥,通过 Bird 的共享入门域名发送邮件,然后查看结果。完成本指南无需验证发件域名,也无需发布 DNS 记录。向客户发送邮件之前,请先验证您自己的域名。

1. 创建 API 密钥

在控制台中,前往 Platform tools > API keys 并创建密钥。密钥按区域划分,格式类似 bk_us1_... 或 bk_eu1_...;前缀中的区域决定应调用哪个 API 主机:https://us1.platform.bird.com 或 https://eu1.platform.bird.com。

Bird 控制台中的 API Keys 页面,列出各密钥的掩码前缀、权限范围和最近使用时间

完整密钥仅在创建时显示一次。请将其复制到安全的位置,然后将其导出为环境变量,以便第 2 步中的代码片段读取:

代码示例
export BIRD_API_KEY="bk_us1_..."

2. 发送电子邮件

从 onboarding@messagebird.dev 发送。这是 Bird 的共享入门域名,无需任何设置即可在您的工作区中使用。将收件人设为 delivered@messagebird.dev,这是一个始终投递成功的沙盒收件人,因此无需真实邮箱也能得到确定的结果。

cURL 调用使用的是美国主机。如果您的密钥以 bk_eu1_ 开头,请改为调用 https://eu1.platform.bird.com。SDK 会从您的密钥中读取区域并自动选择主机。TypeScript 选项卡需要 npm install @messagebird/sdk。

import { BirdClient } from "@messagebird/sdk";

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

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);

如需各语言或框架的完整安装和运行步骤,请参阅 SDK 快速入门。

3. 查看结果

API 返回 202,表示 Bird 已接受此次发送并将异步处理。投递状态需要另行查询。*_count 字段记录收件人在各投递状态间的变化。在初始响应中,有一个收件人已被接受,尚无收件人投递成功。

代码示例
{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "onboarding@messagebird.dev" },
  "to": [{ "email": "delivered@messagebird.dev" }],
  "subject": "Hello from Bird",
  "accepted_count": 1,
  "processed_count": 0,
  "delivered_count": 0,
  "deferred_count": 0,
  "bounced_count": 0,
  "complained_count": 0,
  "rejected_count": 0,
  "open_count": 0,
  "click_count": 0,
  "track_opens": true,
  "track_clicks": true,
  "created_at": "2026-07-23T13:58:20.866Z"
}

按 em_ ID 获取该消息,即可查看其当前状态。消息会从 accepted 经过 processed 变为 delivered。持续轮询,直到沙盒消息达到 delivered:

const msg = await bird.email.get("em_abc123");
msg.status; // "accepted" | "processed" | "delivered" | "bounced" | …
msg.delivered_count;
msg.bounced_count;
console.log(msg.subject, msg.subject_recipient_id);

在 cURL 标签页中,替换 {region} 和 {message_id},并用 $BIRD_API_KEY 代替 $TOKEN。

此时读取结果显示 status: "delivered"、delivered_count: 1 以及 delivered_at 时间戳。关于 delivered 对真实收件人意味着什么,请参阅事件指南。

由于您发送到的是 delivered@messagebird.dev,结果是确定的:消息会经过 Bird 的真实投递管道,包括生产环境的事件和 webhook 格式,但不会进入任何真实邮箱。要测试退信,请发送到 bounce@messagebird.dev。测试沙盒指南列出了所有沙盒地址及其模拟结果。

关于引导域名

共享发件人 onboarding@messagebird.dev 供入门引导使用,有以下限制:

  • 除 @messagebird.dev 沙盒地址外,它只投递给您工作区中已验证的成员;其他任何收件人都会被拒绝,并返回 422。
  • 每个组织每个 UTC 日最多发送给 50 个收件人,所有 to、cc 和 bcc 地址均计入,沙盒收件人也包括在内。超出上限后,API 会返回 429。

准备向真实客户发送邮件时,请验证您自己的发件域名,并在 from 中填入您自己的地址;请求中的其他内容保持不变。

后续步骤