Réservez votre première boîte aux lettres d'agent

Ce guide vous fait mener une conversation bidirectionnelle complète : réservez une boîte de réception sur inbox.ai, recevez un message dans un fil de discussion, lisez-le, puis répondez. Vous n'avez pas besoin de vérifier un domaine ni d'exploiter un serveur de messagerie.

1. Créez une clé API

Dans le tableau de bord, ouvrez Platform tools > API keys et créez une clé. Dans le groupe Email, activez les portées mailbox et mailbox_management. Les clés ont la forme bk_us1_... ou bk_eu1_... ; la région indiquée dans le préfixe détermine l'hôte API.

Exemple de code

export BIRD_API_KEY="bk_us1_..."

Utilisez name pour le nom d'expéditeur que voient les destinataires. Définissez display_name pour donner à votre équipe un autre libellé de boîte aux lettres ; sinon, ce libellé reprend name.

2. Réservez une boîte aux lettres

Créez une boîte aux lettres sur le domaine partagé inbox.ai. Si vous omettez la partie locale, Bird génère une adresse disponible. La politique de réception open accepte le courrier, sauf si une règle de réception le bloque.

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

La réponse contient l'id de la boîte aux lettres et l'address réservée pour vous. Envoyez un e-mail à cette adresse depuis n'importe quel client de messagerie afin que l'étape suivante ait un message à lire.

3. Lisez le fil de discussion

Chaque e-mail entrant devient un fil de discussion dans la boîte aux lettres. Listez les fils, puis lisez les messages du premier.

Un fil de boîte aux lettres dans le tableau de bord Bird montrant un message entrant et une réponse dans la boucle de conversation bidirectionnelle

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"

Lisez ensuite les messages de ce fil :

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"

Chaque message indique sa direction (inbound) et son id (un message reçu porte le préfixe rem_). Ajoutez include=extracted_text pour inclure le corps sans citations : le nouveau contenu, sans l'historique cité qu'un agent devrait sinon retirer lui-même.

Pour éviter l'interrogation périodique, abonnez-vous au webhook email_mailbox.message_received. Il se déclenche lorsqu'un message entrant arrive dans la boîte de réception. Consultez la référence des événements.

4. Répondre

Répondez au message reçu en utilisant son ID rem_ obtenu à l'étape 3. La réponse reste dans le même fil et part de l'adresse de votre boîte aux lettres :

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

Vous savez maintenant réserver une boîte, recevoir, lire et répondre. Pour lancer une conversation plutôt que répondre à une autre, rédigez un nouveau message depuis la boîte aux lettres (POST /v1/email/mailboxes/{id}/messages), ce qui ouvre un nouveau fil.

Étapes suivantes

Boîtes aux lettres d'agent : fonctionnement des fils, des règles de réception, de l'envoi et de la conservation.
Serveur MCP : exécutez la même boucle depuis un agent IA via le serveur MCP.
CLI : bird email mailboxes et bird email threads pour le terminal.
Démarrages rapides SDK : guides pas à pas SDK en Go, Python et TypeScript.

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Mailbox API

Obtenir un guide d'implémentation