Rivendica la tua prima casella di posta per agenti
Questa guida completa una conversazione bidirezionale: rivendica una casella 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 Developers > Chiavi API e crea una chiave. Nel gruppo Email, abilita gli scope mailbox e mailbox_management. Le chiavi hanno il formato bk_us1_... o bk_eu1_...; la regione nel prefisso determina l'host API.
Esempio di codice
export BIRD_API_KEY="bk_us1_..."2. Rivendica una casella di posta
Crea una casella di posta sul dominio condiviso inbox.ai. Ometti la parte locale e 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({ 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 opencurl -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"
}'La risposta contiene l'id della casella e l'address rivendicato. Invia un'email a quell'indirizzo da un qualsiasi client di posta per dare al passo successivo qualcosa da leggere.
3. Leggi il thread
La posta in arrivo diventa un thread sulla casella. Elenca i thread, poi leggi i messaggi del primo.
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 listcurl -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"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 inline il corpo senza citazioni: il contenuto nuovo, senza lo storico citato che altrimenti un agente dovrebbe rimuovere manualmente.
Per evitare il polling, iscriviti al webhook email_mailbox.message_received. Si attiva quando un messaggio in arrivo raggiunge la casella. Consulta il riferimento agli eventi.
4. Rispondi
Rispondi al messaggio ricevuto. Usa il suo ID rem_ dal passo 3. La risposta resta nello stesso thread e viene inviata dall'indirizzo della tua casella:
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 rivendicare, ricevere, leggere e rispondere. Per avviare una conversazione anziché rispondere a una, componi un nuovo messaggio sulla casella (POST /v1/email/mailboxes/{id}/messages): si aprirà un nuovo thread.
Passi 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 attraverso il server MCP.
- CLI: bird email mailboxes e bird email threads per il terminale.
- Quickstart SDK: procedure guidate SDK in Go, Python e TypeScript.
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.