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 vive en el dominio compartido inbox.ai o en tu propio dominio de envío habilitado para recepción. 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.
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 interponen ante la bandeja de entrada, ambos verificados contra el remitente del sobre en lugar de la cabecera From:, que es falsificable:
- Política de recepción: el valor predeterminado de todo el buzón.
- open acepta todo lo que pase la autenticació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.
El correo que una regla bloquea, o que no pasa DMARC, se almacena igualmente en el buzón y sigue siendo legible: se archiva fuera de la bandeja de entrada en lugar de descartarse, y no dispara 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 Reenviar 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), email_mailbox.thread_created y los eventos de estado de entrega de los mensajes que envías. Solo el correo de la bandeja se distribuye; el spam y el correo bloqueado por reglas se almacena en silencio, así que un buzón inundado no se amplifica en una avalancha de webhooks. El correo de la bandeja también dispara el evento estándar email.received, de modo que una integración de entrada existente sigue funcionando.
Para una vista en tiempo real sin infraestructura de webhooks, conéctate a GET /v1/email/mailboxes/{mailbox_id}/events. El flujo SSE envía el tipo de evento, el ID de hilo y el ID de mensaje de la actividad del buzón, incluidos spam y llegadas bloqueadas. Obtén los mensajes completos con esos ID. El flujo no repite eventos tras una desconexión. Usa webhooks para entrega duradera y los endpoints de listado para ponerte al día tras un corte.
Retención y borrado
El nivel de retención de un buzón controla cuánto tiempo puedes leer cabeceras de mensaje, texto extraído y 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, configura retention_tier al crear o actualizar. Un nivel que tu plan no incluya se rechaza con E17048.
| Contenido o acción | Ventana de retención |
|---|---|
| Cabeceras de mensaje, texto extraído y adjuntos del buzón | Nivel seleccionado: 30, 90 o 365 días |
| Cuerpos originales en HTML y texto plano | 30 días en todos los niveles |
| MIME en crudo de mensajes recibidos | 30 días en todos los niveles; los mensajes enviados no tienen MIME en crudo almacenado |
| Reenvío de un mensaje en el panel | Requiere el contenido original dentro de su ventana de 30 días |
| Lectura de texto extraído o respuesta con contenido nuevo | Disponible mientras el mensaje esté retenido |
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 en crudo 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 anterior al nuevo corte deja de devolverse enseguida. Tienes diez minutos para deshacerlo, y diez minutos es la única garantía: sube el nivel de nuevo dentro de esa ventana y no se pierde nada. Pasado ese plazo, los mensajes huérfanos pasan a ser candidatos a 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 todavía se esté aplicando. La actualización en segundo plano es independiente de la ventana de diez minutos para deshacer. Bajar una segunda vez se acepta después de que el primer cambio haya actualizado todos los mensajes almacenados. 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 se comparte entre todos los buzones activos o restaurables. Cada buzón informa de 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, el borrado permanente elimina el buzón y sus mensajes restantes. Una vez que comienza el borrado permanente, la restauración se rechaza incluso si la limpieza todavía está en curso. La dirección permanece reservada para tu espacio de trabajo.
Próximos pasos
- Reclama tu primer buzón: la ruta feliz de API desde la creación hasta la respuesta.
- Construye con IA: controla buzones desde un agente a través del servidor MCP.
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Ver la guíaGetting started with emailExplorar la funcionalidadEmailSeguir la ruta de aprendizajeBuild your first integrationGuía de implementaciónSend your first email
Prueba el ejercicio y obtén un resumen de implementación