Reclama tu primer buzón de agente

Esta guía completa una conversación bidireccional: reclama un buzón en inbox.ai, recibe un mensaje en un hilo, léelo y responde. No necesitas verificar un dominio ni ejecutar un servidor de correo.

1. Crea una clave API

En el panel, ve a Developers > Claves API y crea una clave. En el grupo Email, habilita los alcances mailbox y mailbox_management. Las claves tienen el formato bk_us1_... o bk_eu1_...; la región en el prefijo selecciona el host API.

Ejemplo de código

export BIRD_API_KEY="bk_us1_..."

2. Reclama un buzón

Crea un buzón en el dominio compartido inbox.ai. Omite la parte local y Bird genera una dirección disponible. La política de recepción open acepta correo a menos que una regla de recepción lo bloquee.

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

La respuesta incluye el id del buzón y la address reclamada para ti. Envía un correo a esa dirección desde cualquier cliente de correo para darle algo que leer al siguiente paso.

3. Lee el hilo

El correo entrante se convierte en un hilo en el buzón. Lista los hilos y luego lee los mensajes del primero.

Un hilo de buzón en el panel de Bird que muestra un mensaje entrante y una respuesta en el ciclo de conversación bidireccional

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"

Luego lee los mensajes de ese hilo:

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 mensaje incluye su dirección (inbound) y su id (un mensaje recibido tiene el prefijo rem_). Agrega include=extracted_text para incluir en línea el cuerpo sin citas: el contenido nuevo, sin el historial citado que un agente tendría que eliminar por su cuenta.

Para evitar el sondeo, suscríbete al webhook email_mailbox.message_received. Se dispara cuando un mensaje entrante llega al buzón. Consulta la referencia de eventos.

4. Responde

Responde al mensaje recibido. Usa su ID rem_ del paso 3. La respuesta permanece en el mismo hilo y se envía desde la dirección de tu buzón:

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

Ahora puedes reclamar, recibir, leer y responder. Para iniciar una conversación en lugar de contestar una, redacta un mensaje nuevo en el buzón (POST /v1/email/mailboxes/{id}/messages), lo que abre un hilo nuevo.

Próximos pasos

Buzones de agente: cómo funcionan los hilos, las reglas de recepción, el envío y la retención.
Servidor MCP: ejecuta el mismo ciclo desde un agente de IA a través del servidor MCP.
CLI: bird email mailboxes y bird email threads para la terminal.
Inicios rápidos de SDK: tutoriales paso a paso en Go, Python y TypeScript con SDK.

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Explorar la funcionalidadMailbox API

Obtener un resumen de implementación