Klaim mailbox agent pertama Anda

Panduan ini menyelesaikan percakapan dua arah: klaim inbox di inbox.ai, terima pesan ke dalam thread, baca, dan balas. Anda tidak perlu memverifikasi domain atau menjalankan mail server.

1. Buat key API

Di dashboard, buka Developers > API keys dan buat key. Di grup Email, aktifkan scope mailbox dan mailbox_management. Key berbentuk seperti bk_us1_... atau bk_eu1_...; region di awalan menentukan host API.

Contoh kode

export BIRD_API_KEY="bk_us1_..."

2. Klaim mailbox

Buat mailbox di domain inbox.ai bersama. Kosongkan local part dan Bird akan membuat alamat yang tersedia. Kebijakan penerimaan open menerima email kecuali ada receive rule yang memblokirnya.

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"
  }'

Respons berisi id mailbox dan address yang diklaim untuk Anda. Kirim email ke alamat tersebut dari mail client mana pun agar langkah berikutnya memiliki sesuatu untuk dibaca.

3. Baca thread

Email masuk menjadi thread di mailbox. Tampilkan daftar thread, lalu baca pesan di thread pertama.

Thread mailbox di dashboard Bird menampilkan pesan masuk dan balasan dalam loop percakapan dua arah

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"

Lalu baca pesan di thread tersebut:

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"

Setiap pesan membawa arah (inbound) dan id (pesan yang diterima diawali rem_). Tambahkan include=extracted_text untuk menyisipkan body tanpa kutipan: konten baru, tanpa riwayat kutipan yang seharusnya harus dihapus sendiri oleh agent.

Untuk menghindari polling, daftarkan webhook email_mailbox.message_received. Webhook ini aktif saat pesan masuk tiba di inbox. Lihat referensi events.

4. Balas

Balas pesan yang diterima. Gunakan ID rem_ dari langkah 3. Balasan tetap berada di thread yang sama dan dikirim dari alamat mailbox Anda:

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."
  }'

Anda sekarang dapat mengklaim, menerima, membaca, dan membalas. Untuk memulai percakapan alih-alih menjawab, buat pesan baru di mailbox (POST /v1/email/mailboxes/{id}/messages), yang akan membuka thread baru.

Langkah berikutnya

Mailbox agen: cara kerja thread, aturan penerimaan, pengiriman, dan retensi.
Server MCP: jalankan alur yang sama dari agen AI melalui server MCP.
CLI: bird email mailboxes dan bird email threads untuk terminal.
Quickstart SDK: panduan langkah demi langkah SDK untuk Go, Python, dan TypeScript.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Jelajahi kemampuannyaMailbox API

Dapatkan ringkasan implementasi