发送您的第一封电子邮件
创建 API 密钥,通过 Bird 的共享入门域名发送邮件,然后查看结果。完成本指南无需验证发件域名,也无需发布 DNS 记录。向客户发送邮件之前,请先验证您自己的域名。
1. 创建 API 密钥
在控制台中,前往 Platform tools > API keys 并创建密钥。密钥按区域划分,格式类似 bk_us1_... 或 bk_eu1_...;前缀中的区域决定应调用哪个 API 主机:https://us1.platform.bird.com 或 https://eu1.platform.bird.com。

完整密钥仅在创建时显示一次。请将其复制到安全的位置,然后将其导出为环境变量,以便第 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);from bird import APIError, Bird
with Bird() as client:
try:
message = client.email.send(
from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
to=["delivered@messagebird.dev"],
subject="Hello from Bird",
html="<p>My first Bird email.</p>",
)
print(message.id, message.status)
except APIError as err:
print("send failed:", err)package main
import (
"encoding/json"
"errors"
"log"
"net/http"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
http.HandleFunc("POST /send", func(w http.ResponseWriter, r *http.Request) {
msg, err := client.Email.Send(r.Context(), bird.EmailSendParams{
From: "onboarding@messagebird.dev",
To: []string{"delivered@messagebird.dev"},
Subject: "Hello from Bird",
HTML: "<p>My first Bird email.</p>",
})
if err != nil {
var apiErr *bird.APIError
if errors.As(err, &apiErr) {
http.Error(w, apiErr.Error(), apiErr.StatusCode)
return
}
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusAccepted)
_ = json.NewEncoder(w).Encode(msg)
})
log.Fatal(http.ListenAndServe(":3000", nil))
}<?php
// Send your first email. Set BIRD_API_KEY in your environment, then run:
// php examples/quickstart-email.php
declare(strict_types=1);
require __DIR__ . '/../vendor/autoload.php';
use MessageBird\Bird;
$bird = new Bird(getenv('BIRD_API_KEY') ?: '');
$message = $bird->email->send(
from: 'Bird <onboarding@messagebird.dev>',
to: ['delivered@messagebird.dev'],
subject: 'Hello from Bird',
html: '<p>My first Bird email.</p>',
);
echo $message->getId(), ' ', $message->getStatus(), "\n";bird email send \
--from 'Bird <onboarding@messagebird.dev>' \
--html '<p>My first Bird email.</p>' \
--subject 'Hello from Bird' \
--to delivered@messagebird.devcurl -X POST "https://us1.platform.bird.com/v1/email/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "onboarding@messagebird.dev", "name": "Bird" },
"to": ["delivered@messagebird.dev"],
"subject": "Hello from Bird",
"html": "<p>My first Bird email.</p>"
}'如需各语言或框架的完整安装和运行步骤,请参阅 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);message = client.email.get("em_abc123")
print(message.id, message.status, message.delivered_count)
print(message.subject, message.subject_recipient_id)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Email.Get(context.Background(), "em_abc123")
if err != nil {
log.Fatal(err)
}
fmt.Println(*msg.Status, *msg.DeliveredCount)
fmt.Println(msg.Subject)
if msg.SubjectRecipientId != nil {
fmt.Println(*msg.SubjectRecipientId)
}
}$message = $bird->email->get('em_01krdgeqcxet5s7t44vh8rt9mg');
echo $message->getStatus();
echo $message->getSubject(), ' ', $message->getSubjectRecipientId();bird email get <message-id>curl -X GET "https://{region}.platform.bird.com/v1/email/messages/{message_id}" \
-H "Authorization: Bearer $TOKEN"在 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 中填入您自己的地址;请求中的其他内容保持不变。
后续步骤
- 各 SDK 快速入门:用你的语言和框架完成同样的流程。
- 发件域名:验证你自己的域名,用于生产环境发送。
- 测试沙盒:所有沙盒地址及其触发的事件。
- 电子邮件 API 参考:完整的请求和响应结构。
- 邮件入门:控制台引导流程的视频,内容比本页更深入,还会添加发件域名及其 DNS 记录