Buzones de agente

Un buzón de agente es una bandeja de entrada direccionable que tu código gestiona a través de la API. Lee y filtra sus hilos, responde mensajes o redacta correo nuevo sin ejecutar un servidor IMAP ni analizar MIME en crudo.

Un buzón se aloja en el dominio compartido inbox.ai o en uno de tus propios dominios de envío. Su dirección se reserva en el momento en que lo creas y sigue siendo tuya: la parte local queda reservada para tu espacio de trabajo y nunca se asigna a nadie más, ni siquiera después de que elimines el buzón.

Direcciones

Cada buzón tiene una dirección, {local_part}@inbox.ai. Puedes obtener una dirección de dos formas:

• Generada: omite la parte local y generamos una libre de colisiones para ti (a7f3k2@inbox.ai). Siempre disponible.
• Personalizada: solicita una parte local específica (support@inbox.ai). Los identificadores personalizados son globalmente únicos, se asignan por orden de llegada y forman parte de la cuota de un plan de pago; un espacio de trabajo gratuito usa direcciones generadas.

Una dirección es inmutable una vez creada. Para cambiarla, crea un buzón nuevo y elimina el anterior. La parte local anterior se retiene durante 30 días (su ventana de restauración) antes de poder reclamarse de nuevo, y permanece reservada para tu espacio de trabajo.

En tu propio dominio, pasa domain al crear el buzón y elige cualquier parte local, como support@acme.com. La forma en que el correo llega al buzón depende de la configuración del dominio:

• Recepción habilitada: el correo llega directamente en cuanto los registros MX del dominio apuntan a nosotros. Consulta Recepción de correo.
• Recepción no habilitada: el dominio necesita una propiedad verificada, y tus registros MX se mantienen como están. El buzón recibe una forwarding_address, como k7q2mzxw4h6p5ra3@eu1.inbound.bird.com. Añade en tu proveedor de correo actual una regla de reenvío para support@acme.com que apunte a esa dirección. El correo reenviado llega al buzón, y las respuestas y el correo nuevo se siguen enviando desde support@acme.com.

Para un buzón existente en un dominio propio sin dirección de reenvío, abre Mailbox settings y elige Set up forwarding. Así se conservan sin cambios la dirección del buzón, los mensajes, la política de recepción y la retención. Necesitas permiso de escritura para gestionar buzones y una propiedad de dominio verificada en el espacio de trabajo. Si otro espacio de trabajo ha reclamado el dominio para recepción, no puedes obtener aquí una nueva dirección de reenvío.

El equivalente en API es POST /v1/email/mailboxes/{mailbox_id}/forwarding-address, sin cuerpo de solicitud. Devuelve el buzón completo con su forwarding_address. Si repites la solicitud, obtienes la misma dirección, también después de eliminar y restaurar; no rota la dirección ni reactiva un buzón suspendido. El comando de CLI es bird email mailboxes forwarding-address create <mailbox-id>.

Crear una dirección no configura el reenvío en tu proveedor, no modifica el DNS ni verifica la entrega. Si tu proveedor ya recibe correo, conserva sus registros MX y añade allí la regla de reenvío. Si los registros MX apuntan a nosotros, prepara primero el buzón y la regla de reenvío en tu proveedor y luego mueve los registros MX a ese proveedor. Mantén la recepción habilitada mientras se propaga el cambio de DNS. Prueba el reenvío antes de desactivar la recepción directa.

Gmail y Google Workspace envían un mensaje de confirmación a una nueva dirección de reenvío. Ábrelo en este buzón y sigue sus instrucciones de confirmación para terminar la configuración. Microsoft 365 puede requerir que un administrador permita el reenvío externo. Con la política replies_only o allowlist, revisa el correo bloqueado; revisa también el spam y las reglas de recepción. Una política drop no conserva la confirmación: cambia la política de forma explícita antes de solicitar una confirmación nueva. Debes reactivar un buzón suspendido para que acepte mensajes con normalidad.

Conserva una copia en tu proveedor mientras haces pruebas. Envía un mensaje nuevo desde otra cuenta a la dirección original del buzón y abre el mensaje recibido en este buzón. Su dirección Delivered to debe coincidir con la forwarding_address para demostrar la entrega por esa ruta. La API lo expone como delivered_to. Los recuentos de mensajes del buzón incluyen la actividad saliente y no verifican el reenvío.

Para volver a la entrega directa, habilita la recepción, restaura nuestros registros MX y prueba la entrega directa antes de eliminar la regla de reenvío de tu proveedor. Si las rutas se solapan, como con la entrega doble de Google Workspace, cada mensaje puede llegar dos veces al buzón. La dirección de reenvío sigue funcionando cuando se desactiva la recepción directa y no cambia al eliminar y restaurar el buzón.

Hilos y mensajes

El correo recibido y enviado se agrupa en hilos, uno por conversación. Un hilo contiene las direcciones participantes, un contador de no leídos, la dirección de su último mensaje (inbound o outbound) y la marca de tiempo de su actividad más reciente. Las respuestas se incorporan al hilo que contestan; una redacción nueva inicia un hilo nuevo.

Cada mensaje expone cabeceras, texto plano extraído sin el historial citado y archivos adjuntos. Los cuerpos originales están disponibles durante 30 días; el MIME en crudo solo está disponible para mensajes recibidos. Los ID de mensaje llevan un prefijo según la dirección: rem_ para un mensaje recibido, em_ para uno que enviaste.

Decidir qué entra

Dos controles se aplican antes de la bandeja de entrada:

• Política de recepción: el valor predeterminado de todo el buzón.
  • open acepta correo después de las reglas de bloqueo. Los resultados de SPF y DKIM no modifican esta política de admisión.
  • replies_only acepta solo correo que continúe un hilo ya existente en el buzón.
  • allowlist acepta solo remitentes que tus reglas permitan, más respuestas a un hilo existente.
  • drop descarta todo, sin excepciones.
• Reglas de recepción: entradas de permiso o bloqueo por remitente, evaluadas contra una dirección completa o un dominio (una regla de dominio también cubre sus subdominios). Un bloqueo siempre prevalece sobre un permiso.

Una regla de bloqueo coincide con el remitente del sobre o con la dirección From:. Una regla de permiso coincide con el remitente del sobre, o con la dirección From: cuando el mensaje tiene una firma DKIM válida del dominio de esa dirección. La cabecera From: es fácil de falsificar, por lo que un From: sin firmar nunca obtiene un permiso. Esto cubre el correo reenviado, en el que Gmail y Microsoft 365 sustituyen el remitente del sobre por su propia dirección, y el correo de servicios de envío que usan una dirección de rebote distinta. El correo reenviado cuya firma DKIM no se conserva sigue coincidiendo con la dirección del servicio de reenvío.

El correo que una regla bloquea se almacena en el buzón y sigue siendo legible. Se archiva fuera de la bandeja de entrada y no envía ningún webhook. La única excepción es un buzón configurado como drop, que descarta todo en la puerta en lugar de archivarlo.

Envío

Un buzón envía de dos formas a través de la API: responder a un mensaje (el mensaje saliente se incorpora a ese hilo) o redactar un mensaje nuevo (que abre un hilo nuevo). En el panel, abre un mensaje y elige Forward para enviar su cuerpo original y sus adjuntos a nuevos destinatarios, dentro de la ventana de 30 días del contenido original. El correo se envía desde la dirección propia del buzón, con el nombre visible y el Reply-To predeterminado que configuraste en él. El estado de entrega se asocia de vuelta al mensaje enviado, para que puedas ver si una respuesta se entregó o rebotó.

Eventos

Suscríbete a la familia de webhooks email_mailbox.* para controlar un agente sin sondeo: email_mailbox.message_received (correo entrante que llegó a la bandeja de entrada), email_mailbox.thread_created, y los eventos de estado de entrega de los mensajes que envías. Solo el correo de la bandeja de entrada se distribuye; el spam y el correo bloqueado por reglas se almacena en silencio, así que un buzón inundado no puede amplificarse en una avalancha de webhooks. El correo de la bandeja de entrada también dispara el evento estándar email.received, de modo que una integración de entrada existente sigue funcionando. Ambos eventos incluyen resultados de autenticación. Revisa esos campos antes de enrutar automáticamente: que el correo llegue a la bandeja de entrada no significa que el remitente haya sido verificado.

Retención y eliminación

El nivel de retención de un buzón controla durante cuánto tiempo puedes leer encabezados de mensajes, texto extraído y archivos adjuntos del buzón, medido desde el envío o la recepción. El valor predeterminado es 30 días. Si tu plan incluye retención de 90 o 365 días, establece retention_tier al crear o actualizar. Un nivel que tu plan no incluya se rechaza con E17048.

Por ejemplo, en el día 40 un mensaje en un buzón de 90 días todavía tiene texto extraído legible y buscable, y adjuntos retenidos. Puedes responder con contenido nuevo, pero no puedes abrir el cuerpo original, descargar su MIME sin procesar ni reenviarlo. El texto extraído está limitado a 64 KiB por mensaje y puede omitir partes del original. Los adjuntos almacenados antes de que se habilitara la retención extendida de adjuntos conservan su expiración original de aproximadamente 31 días; cambiar de nivel no los migra. Subir el nivel no puede recuperar contenido que ya se haya eliminado.

Los mensajes dejan de ser devueltos por la API cuando su retención expira. Un barrido cada hora procesa la eliminación en segundo plano; la limpieza física puede retrasarse respecto a la expiración de API.

Bajar el nivel surte efecto en las lecturas de inmediato: cualquier mensaje más antiguo que el nuevo límite deja de devolverse al instante. Tienes diez minutos para deshacerlo, y diez minutos es la única garantía: sube el nivel otra vez dentro de esa ventana y no se pierde nada. Pasado ese plazo, los mensajes aislados quedan pendientes de eliminación y el siguiente barrido horario los procesa, así que una subida posterior solo recupera lo que el barrido aún no haya alcanzado.

Subir a un nivel que tu plan incluya se acepta en cualquier momento, incluso mientras un cambio anterior aún se está aplicando. La actualización en segundo plano es independiente de la ventana de deshacer de diez minutos. Bajar una segunda vez se acepta después de que el primer cambio haya actualizado cada mensaje almacenado. La actualización se inicia cada diez minutos y puede tardar horas en buzones grandes. Hasta que se complete, la API devuelve E17050; reintenta más tarde.

Si tu plan establece una cuota finita de almacenamiento de buzón, una sola cuota es compartida por todos los buzones activos o restaurables. Cada buzón informa su parte como size_bytes. Un plan sin cuota finita tiene almacenamiento de buzón ilimitado. Cuando los buzones en conjunto alcanzan una cuota finita, el envío se rechaza con E17049 hasta que liberes espacio en cualquiera de ellos.

Eliminar un buzón detiene la recepción de correo de inmediato. El buzón se puede restaurar durante 30 días, mientras la expiración normal de retención de mensajes continúa. Pasados 30 días, la eliminación permanente borra el buzón y sus mensajes restantes. Una vez que la eliminación permanente comienza, la restauración se rechaza aunque la limpieza aún esté en curso. La dirección permanece reservada para tu espacio de trabajo.

Próximos pasos

• Reclama tu primer buzón: el flujo básico de API desde la creación hasta la respuesta.
• Construye con IA: controla buzones desde un agente a través del servidor MCP.