认领你的第一个智能体邮箱
本指南带你完成一次双向对话：在 inbox.ai 上认领收件箱，将收到的邮件归入会话，读取邮件并回复。你无需验证域名，也无需运行邮件服务器。
1. 创建 API 密钥
在控制台中，前往 Platform tools > API keys 并创建密钥。在 Email 分组下，启用 mailbox 和 mailbox_management 权限范围。密钥形如 bk_us1_... 或 bk_eu1_...；前缀中的区域决定使用哪个 API 主机。
代码示例
export BIRD_API_KEY="bk_us1_..."用 name 设置收件人看到的发件人名称。如需为团队设置不同的邮箱标签，请设置 display_name；否则它与 name 相同。
2. 认领邮箱
在共享的 inbox.ai 域名下创建邮箱。如果省略本地部分，Bird 会生成一个可用地址。open 接收策略会接受邮件，除非某条接收规则将其拦截。
const mailbox = await bird.email.mailboxes.create({ name: "Support" });
console.log(mailbox.address); // "abc123@inbox.ai"mailbox = client.email.mailboxes.create(name="Acme Support")
print(mailbox.id)mailbox, err := client.Email.Mailboxes.Create(context.Background(), bird.EmailMailboxesCreateParams{
Name: bird.Ptr("Support"),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(mailbox.Id, *mailbox.Address)$mailbox = $bird->email->mailboxes->create(
(new MailboxCreate())
->setName('Acme Support'),
);
echo $mailbox->getId(), ' ', $mailbox->getAddress();bird email mailboxes create --name 'My Agent' --receive-policy opencurl -X POST "https://us1.platform.bird.com/v1/email/mailboxes" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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 listcurl -X GET "https://{region}.platform.bird.com/v1/email/threads" \
-H "Authorization: Bearer $TOKEN" \
--url-query "labels=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 可内联返回去除引用后的正文，即只包含新内容，不含引用的历史记录，否则智能体需要自行去除这些内容。
如果不想轮询，可以订阅 email_mailbox.message_received webhook。收到的消息到达收件箱时会触发该 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），这会开启一个新会话。