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 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.
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 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 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.
| Contenido o acción | Ventana de retención |
|---|---|
| Encabezados de mensajes, 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 sin procesar de mensajes recibidos | 30 días en todos los niveles; los mensajes enviados no tienen MIME sin procesar 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 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: 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