Klaim kotak surat agen pertama Anda

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

1. Buat kunci API

Di dasbor, buka Platform tools > API keys dan buat kunci. Di grup Email, aktifkan cakupan mailbox dan mailbox_management. Kunci berbentuk bk_us1_... atau bk_eu1_...; region pada awalan kunci menentukan host API.

Contoh kode

export BIRD_API_KEY="bk_us1_..."

Gunakan name untuk nama pengirim yang dilihat penerima. Atur display_name untuk memberi tim Anda label kotak surat yang berbeda; jika tidak diatur, nilainya mengikuti name.

2. Klaim kotak surat

Buat kotak surat di domain bersama inbox.ai. Jika Anda tidak mengisi bagian lokal alamat, Bird akan membuat alamat yang tersedia. Kebijakan penerimaan open menerima email kecuali ada aturan penerimaan yang memblokirnya.

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 open

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

Respons berisi id kotak surat dan address yang diklaim untuk Anda. Kirim email ke alamat tersebut dari klien email mana pun agar ada pesan yang bisa dibaca pada langkah berikutnya.

3. Baca thread

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

Thread mailbox di dashboard Bird yang menampilkan pesan masuk dan balasan dalam alur 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 "labels=urgent" \
  --url-query "participant=billing@acme.com" \
  --url-query "subject=quarterly invoice" \
  --url-query "limit=25"

Lalu baca pesan-pesan dalam 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 mencantumkan arahnya (inbound) dan id-nya (pesan yang diterima berawalan rem_). Tambahkan include=extracted_text untuk menyertakan isi pesan tanpa kutipan secara langsung: konten baru saja, tanpa riwayat kutipan yang jika tidak harus dihapus sendiri oleh agen.

Agar tidak perlu melakukan polling, berlangganan webhook email_mailbox.message_received. Webhook ini terpicu saat pesan masuk tiba di inbox. Lihat referensi events.

4. Balas

Balas pesan yang diterima. Gunakan ID rem_ pesan tersebut 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."
  }'

Kini Anda dapat mengklaim, menerima, membaca, dan membalas. Untuk memulai percakapan alih-alih menjawabnya, tulis 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.
Panduan memulai cepat SDK: panduan langkah demi langkah SDK untuk Go, Python, dan TypeScript.

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.

Mailbox API

Dapatkan ringkasan implementasi