Registre sua primeira caixa de correio de agente

Este guia completa uma conversa bidirecional: registre uma caixa de entrada no inbox.ai, receba uma mensagem em uma conversa, leia-a e responda. Você não precisa verificar um domínio nem operar um servidor de e-mail.

1. Crie uma chave de API

No painel, acesse Platform tools > API keys e crie uma chave. No grupo Email, ative os escopos mailbox e mailbox_management. As chaves têm o formato bk_us1_... ou bk_eu1_...; a região no prefixo define o host API.

Exemplo de código

export BIRD_API_KEY="bk_us1_..."

Use name para o nome de remetente que os destinatários veem. Defina display_name para dar à sua equipe um rótulo diferente para a caixa de correio; caso contrário, ele segue name.

2. Registre uma caixa de correio

Crie uma caixa de correio no domínio compartilhado inbox.ai. Se você omitir a parte local, o Bird gera um endereço disponível. A política de recebimento open aceita e-mails, a menos que uma regra de recebimento os bloqueie.

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

A resposta traz o id da caixa de correio e o address registrado para você. Envie um e-mail para esse endereço de qualquer cliente de e-mail para que a próxima etapa tenha algo para ler.

3. Leia a conversa

Cada e-mail recebido vira uma conversa na caixa de correio. Liste as conversas e depois leia as mensagens da primeira.

Uma thread de caixa de correio no painel da Bird mostrando uma mensagem recebida e uma resposta no ciclo de conversa bidirecional

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"

Em seguida, leia as mensagens dessa 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"

Cada mensagem informa sua direção (inbound) e seu id (uma mensagem recebida tem o prefixo rem_). Adicione include=extracted_text para incluir o corpo sem citações: o conteúdo novo, sem o histórico citado que, de outra forma, o agente teria que remover sozinho.

Para não precisar consultar a API repetidamente, assine o webhook email_mailbox.message_received. Ele é disparado quando uma mensagem recebida chega à caixa de entrada. Consulte a referência de eventos.

4. Responda

Responda à mensagem recebida usando o ID rem_ dela, obtido na etapa 3. A resposta permanece na mesma thread e é enviada a partir do endereço da sua caixa de correio:

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

Agora você já sabe criar uma caixa de correio, receber, ler e responder mensagens. Para iniciar uma conversa em vez de responder a uma, escreva uma nova mensagem na caixa de correio (POST /v1/email/mailboxes/{id}/messages), o que abre uma nova thread.

Próximos passos

Caixas de correio de agentes: como funcionam as threads, as regras de recebimento, o envio e a retenção.
Servidor MCP: execute o mesmo ciclo a partir de um agente de IA pelo servidor MCP.
CLI: bird email mailboxes e bird email threads para o terminal.
Guias de início rápido de SDK: passo a passo de SDK em Go, Python e TypeScript.

Continue com a documentação, guias e exemplos sobre este tópico.

Mailbox API

Obtenha um resumo de implementação