Claim je eerste agent-mailbox

Deze handleiding doorloopt een tweerichtingsgesprek: claim een inbox op inbox.ai, ontvang een bericht in een thread, lees het en antwoord. Je hoeft geen domein te verifiëren en geen mailserver te draaien.

1. Maak een API-key aan

Ga in het dashboard naar Developers > API keys en maak een key aan. Schakel onder de groep Email de scopes mailbox en mailbox_management in. Keys zien eruit als bk_us1_... of bk_eu1_...; de regio in het prefix bepaalt de API-host.

Codevoorbeeld

export BIRD_API_KEY="bk_us1_..."

2. Claim een mailbox

Maak een mailbox aan op het gedeelde inbox.ai-domein. Laat het lokale deel weg en Bird genereert een beschikbaar adres. Het ontvangstbeleid open accepteert mail tenzij een ontvangregel het blokkeert.

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

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

3. Lees de thread

Inkomende mail wordt een thread op de mailbox. Toon de threads en lees vervolgens de berichten in de eerste.

Een mailbox-thread in het Bird-dashboard met een inkomend bericht en een antwoord in de tweerichtingsgespreklus

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"

Lees vervolgens de berichten van 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 prefix rem_). Voeg include=extracted_text toe om de body zonder aanhalingen inline weer te geven: de nieuwe inhoud, zonder de geciteerde geschiedenis die een agent anders zelf zou moeten verwijderen.

Abonneer je op de email_mailbox.message_received-webhook om polling te vermijden. Deze wordt geactiveerd wanneer een inkomend bericht de inbox bereikt. Zie de events-referentie.

4. Antwoord

Antwoord op het ontvangen bericht. Gebruik het rem_-ID uit stap 3. Het antwoord blijft in dezelfde thread en wordt verstuurd 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 claimen, ontvangen, lezen en antwoorden. Om een gesprek te starten in plaats van er een te beantwoorden, stel je een nieuw bericht op via de mailbox (POST /v1/email/mailboxes/{id}/messages), waarmee een nieuwe thread wordt geopend.

Vervolgstappen

Agent-mailboxen: hoe threads, ontvangstregels, verzending en retentie werken.
MCP-server: doorloop dezelfde lus vanuit een AI-agent via de MCP-server.
CLI: bird email mailboxes en bird email threads voor de terminal.
SDK-quickstarts: stapsgewijze handleidingen voor Go, Python en TypeScript met SDK.

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Ontdek de mogelijkheidMailbox API

Ontvang een implementatieoverzicht