认领你的第一个 Agent 邮箱

本指南完成一次双向对话：在 inbox.ai 上认领收件箱、将消息接收到会话中、阅读并回复。你无需验证域名或运行邮件服务器。

1. 创建 API 密钥

在控制台中，前往 Developers > API keys 并创建一个密钥。在 Email 分组下，启用 mailbox 和 mailbox_management 权限范围。密钥形如 bk_us1_... 或 bk_eu1_...；前缀中的区域决定 API 主机。

代码示例

export BIRD_API_KEY="bk_us1_..."

2. 认领邮箱

在共享的 inbox.ai 域上创建邮箱。省略本地部分，Bird 会生成一个可用地址。open 接收策略默认接受邮件，除非接收规则将其拦截。

const mailbox = await bird.email.mailboxes.create({ display_name: "Support" });
console.log(mailbox.address); // "abc123@inbox.ai"

mailbox = client.email.mailboxes.create(display_name="Acme Support")
print(mailbox.id)

mailbox, err := client.Email.Mailboxes.Create(context.Background(), bird.EmailMailboxesCreateParams{
	DisplayName: bird.Ptr("Support"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(mailbox.Id, *mailbox.Address)

$mailbox = $bird->email->mailboxes->create(
    (new MailboxCreate())
        ->setDisplayName('Acme Support'),
);
echo $mailbox->getId(), ' ', $mailbox->getAddress();

bird email mailboxes create \
  --display-name 'My Agent' \
  --receive-policy open

curl -X POST "https://us1.platform.bird.com/v1/email/mailboxes" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "My Agent",
    "receive_policy": "open"
  }'

响应中包含邮箱 id 和为你认领的 address。用任意邮件客户端向该地址发送一封邮件，以便下一步有内容可读。

3. 读取会话

入站邮件会成为邮箱上的一个会话。先列出会话，然后读取第一个会话中的消息。

for await (const thread of bird.email.threads.list({ mailbox_id: "mbx_01abc" })) {
  console.log(thread.id, thread.subject);
}

for thread in client.email.threads.list(mailbox_id="mbx_01krdgeqcxet5s7t44vh8rt9mg"):
    print(thread.id, thread.subject)

for thread, err := range client.Email.Threads.List(context.Background(), bird.EmailThreadsListParams{}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(thread.Id)
}

foreach ($bird->email->threads->list(['mailbox_id' => 'mbx_01krdgeqcxet5s7t44vh8rt9mg']) as $thread) {
    echo $thread->getId(), ' ', $thread->getSubject(), "\n";
}

bird email threads list

curl -X GET "https://{region}.platform.bird.com/v1/email/threads" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "label=urgent" \
  --url-query "participant=billing@acme.com" \
  --url-query "subject=quarterly invoice" \
  --url-query "limit=25"

然后读取该会话的消息：

for await (const msg of bird.email.threads.messages.list("thr_01abc")) {
  console.log(msg.id, msg.direction);
}

for message in client.email.threads.messages.list("thr_01krdgeqcxet5s7t44vh8rt9mg"):
    print(message.id, message.subject)

for msg, err := range client.Email.Threads.Messages.List(context.Background(), "thr_123", bird.EmailThreadsMessagesListParams{}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, msg.Direction)
}

foreach ($bird->email->threads->messages->list('thr_01krdgeqcxet5s7t44vh8rt9mg') as $message) {
    echo $message->getId(), ' ', $message->getDirection(), "\n";
}

bird email threads messages list <thread-id>

curl -X GET "https://{region}.platform.bird.com/v1/email/threads/{thread_id}/messages" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "label=unread" \
  --url-query "limit=25"

每条消息包含其方向（inbound）和 id（接收到的消息以 rem_ 为前缀）。添加 include=extracted_text 可内联去除引用后的正文：即新内容，不含引用历史，否则 Agent 需要自行剥离这些引用。

要避免轮询，请订阅 email_mailbox.message_received webhook。当入站消息到达收件箱时它会触发。参阅事件参考文档。

4. 回复

回复收到的消息。使用步骤 3 中获取的 rem_ ID。回复会留在同一会话中，并从你邮箱的地址发送：

const reply = await bird.email.threads.messages.reply("thr_01abc", "rem_01xyz", {
  text: "Thanks for reaching out!",
});
console.log(reply.id);

reply = client.email.threads.messages.reply(
    "thr_01krdgeqcxet5s7t44vh8rt9mg", "rem_01krdgeqcxet5s7t44vh8rt9mg",
    text="Thanks for reaching out!",
)
print(reply.id)

reply, err := client.Email.Threads.Messages.Reply(context.Background(), "thr_123", "rem_456", bird.EmailThreadsMessagesReplyParams{
	Text: bird.Ptr("Thanks for reaching out!"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(reply.Id)

$reply = $bird->email->threads->messages->reply(
    'thr_01krdgeqcxet5s7t44vh8rt9mg',
    'rem_01krdgeqcxet5s7t44vh8rt9mg',
    (new EmailThreadMessageReplyRequest())
        ->setText('Thanks, looking into it now.')
        ->setReplyAll(true),
);
echo $reply->getId();

bird email threads messages reply <thread-id> <message-id> \
  --text 'Thanks, confirming we received your request.'

curl -X POST "https://{region}.platform.bird.com/v1/email/threads/{thread_id}/messages/{message_id}/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Thanks, confirming we received your request."
  }'

现在你可以认领、接收、读取和回复邮件了。要主动发起对话而非回复对话，请在邮箱上撰写新消息（POST /v1/email/mailboxes/{id}/messages），这将打开一个新会话。

后续步骤

Agent 邮箱：会话线程、接收规则、发送和保留策略的工作方式。
MCP server：通过 MCP server 从 AI agent 运行相同的流程。
CLI：适用于终端的 bird email mailboxes 和 bird email threads。
SDK 快速入门：Go、Python 和 TypeScript SDK 教程。