Attiva la tua prima casella di posta per agenti

Questa guida completa una conversazione bidirezionale: attiva una casella di posta su inbox.ai, ricevi un messaggio in un thread, leggilo e rispondi. Non devi verificare un dominio né gestire un server di posta.

1. Crea una chiave API

Nella dashboard, vai a Platform tools > API keys e crea una chiave. Nel gruppo Email, abilita gli scope mailbox e mailbox_management. Le chiavi hanno la forma bk_us1_... o bk_eu1_...; la regione nel prefisso determina l'host API.

Esempio di codice

export BIRD_API_KEY="bk_us1_..."

Usa name per il nome del mittente visualizzato dai destinatari. Imposta display_name per assegnare alla casella un'etichetta diversa per il tuo team; altrimenti assume il valore di name.

2. Attiva una casella di posta

Crea una casella di posta sul dominio condiviso inbox.ai. Se ometti la parte locale, Bird genera un indirizzo disponibile. La policy di ricezione open accetta la posta, a meno che una regola di ricezione non la blocchi.

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 risposta contiene il valore id della casella di posta e l'indirizzo address attivato per te. Invia un'email a quell'indirizzo da un qualsiasi client di posta, così il passaggio successivo avrà un messaggio da leggere.

3. Leggi il thread

La posta in arrivo diventa un thread nella casella di posta. Elenca i thread, poi leggi i messaggi del primo.

Un thread di una casella di posta nella dashboard di Bird che mostra un messaggio in entrata e una risposta nel ciclo di conversazione bidirezionale

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"

Poi leggi i messaggi di quel 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"

Ogni messaggio riporta la sua direzione (inbound) e il suo id (un messaggio ricevuto ha il prefisso rem_). Aggiungi include=extracted_text per includere il corpo senza citazioni: il nuovo contenuto, senza la cronologia citata che altrimenti l'agente dovrebbe rimuovere da solo.

Per evitare il polling, iscriviti al webhook email_mailbox.message_received. Si attiva quando un messaggio in entrata arriva nella casella. Consulta il riferimento sugli eventi.

4. Rispondi

Rispondi al messaggio ricevuto usando il suo ID rem_ del passaggio 3. La risposta resta nello stesso thread e parte dall'indirizzo della tua casella di posta:

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

Ora puoi creare una casella, ricevere, leggere e rispondere. Per avviare una conversazione invece di rispondere a una, componi un nuovo messaggio sulla casella di posta (POST /v1/email/mailboxes/{id}/messages): si apre così un nuovo thread.

Passaggi successivi

Caselle di posta per agenti: come funzionano thread, regole di ricezione, invio e conservazione.
Server MCP: esegui lo stesso ciclo da un agente AI tramite il server MCP.
CLI: bird email mailboxes e bird email threads per il terminale.
Guide rapide SDK: procedure guidate SDK per Go, Python e TypeScript.

Continua con la documentazione, le guide e gli esempi per questo argomento.

Mailbox API

Ottieni un brief di implementazione