Claim je eerste agentmailbox

In deze handleiding voer je een volledig gesprek in twee richtingen: je claimt een inbox op inbox.ai, ontvangt een bericht in een thread, leest het en antwoordt. Je hoeft geen domein te verifiëren en geen mailserver te draaien.

1. Maak een API-sleutel aan

Ga in het dashboard naar Platform tools > API keys en maak een sleutel aan. Schakel onder de groep Email de scopes mailbox en mailbox_management in. Sleutels zien eruit als bk_us1_... of bk_eu1_.... De regio in het voorvoegsel bepaalt de API-host.

Codevoorbeeld

export BIRD_API_KEY="bk_us1_..."

Gebruik name voor de afzendernaam die ontvangers zien. Stel display_name in om je team een ander mailboxlabel te geven. Anders volgt het name.

2. Claim een mailbox

Maak een mailbox aan op het gedeelde domein inbox.ai. Laat je het lokale deel weg, dan genereert Bird een beschikbaar adres. Het ontvangstbeleid open accepteert e-mail, tenzij een ontvangstregel die blokkeert.

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

Het antwoord bevat de id van de mailbox en het address dat voor je is geclaimd. Stuur vanuit een willekeurige mailclient een e-mail naar dat adres, zodat de volgende stap iets te lezen heeft.

3. Lees de thread

Inkomende e-mail wordt een thread in de mailbox. Vraag de lijst met threads op en lees daarna de berichten in de eerste thread.

Een mailboxthread in het Bird-dashboard met een inkomend bericht en een antwoord in de tweerichtingsgesprekslus

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"

Lees daarna de berichten in die thread:

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"

Elk bericht bevat zijn richting (inbound) en zijn id (een ontvangen bericht heeft het voorvoegsel rem_). Voeg include=extracted_text toe om de body zonder citaten inline op te nemen: de nieuwe inhoud, zonder de geciteerde geschiedenis die een agent anders zelf zou moeten verwijderen.

Abonneer je op de webhook email_mailbox.message_received om pollen te vermijden. Die wordt geactiveerd zodra een inkomend bericht de inbox bereikt. Zie de referentie voor events.

4. Antwoorden

Beantwoord het ontvangen bericht. Gebruik daarvoor de rem_-ID uit stap 3. Het antwoord blijft in dezelfde thread en wordt verzonden vanaf het adres van je mailbox:

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

Je kunt nu een mailbox claimen en berichten ontvangen, lezen en beantwoorden. Wil je zelf een gesprek beginnen in plaats van er een te beantwoorden, stel dan een nieuw bericht op in de mailbox (POST /v1/email/mailboxes/{id}/messages). Daarmee open je een nieuwe thread.

Volgende stappen

Agentmailboxen: hoe threads, ontvangstregels, verzenden en bewaring werken.
MCP-server: voer dezelfde lus uit vanuit een AI-agent via de MCP-server.
CLI: bird email mailboxes en bird email threads voor de terminal.
SDK-quickstarts: stapsgewijze uitleg voor SDK in Go, Python en TypeScript.

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Mailbox API

Ontvang een implementatieoverzicht