Sign inGet Started

发送你的第一封邮件

创建一个 API 密钥,通过 Bird 的共享引导域名发送邮件,然后查看结果。本指南无需验证发送域名或发布 DNS 记录。在向客户发送邮件之前,请先验证你自己的域名。

1. 创建 API 密钥

在控制面板中,前往 Developers > API keys 并创建一个密钥。密钥按区域划分,格式类似 bk_us1_... 或 bk_eu1_...;前缀中的区域标识告诉你应调用哪个 API 主机:https://us1.platform.bird.com 或 https://eu1.platform.bird.com。
Bird 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;
在 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 中填入你自己的地址;请求中的其他内容保持不变。

后续步骤