Inbox

Un Inbox es una dirección de correo enrutable con una política de procesamiento. Cada inbox pertenece a un workspace y puede asociar un único agente para procesamiento automatizado.

Propósito

• Proveer una dirección de correo única para un caso de uso (triaje de soporte, ingesta de facturas, revisión de contratos, etc.).
• Definir filtros que deciden si un correo entrante es approved o rejected.
• Controlar la política de adjuntos (cantidad, tamaño por archivo, tamaño total).
• Enrutar opcionalmente cada correo aprobado a un Agent para procesamiento por LLM.

Importante: el aprovisionamiento es solo en base de datos

Crear un inbox no llama a AWS. El inbound de AWS SES coincide por dominio — con la Domain Identity verificada y los registros MX apuntados, toda dirección *@inbox.{env}.kobana.com.br llega a SES sin importar si existe en nuestra base de datos. El registro de inbox es lo que hace que la dirección sea enrutable en adelante; sin él, el correo se descarta en process-email con rejection_reason=recipient_unknown.

Schema

Campo	Tipo	Descripción
id	UUID	ID interno.
external_id	UUID	ID estable del sistema de origen. Único.
workspace_id	UUID	Workspace propietario.
agent_id	UUID | null	Agente opcional para correos aprobados.
label	string	Etiqueta legible.
email	string	La dirección enrutable. Globalmente única.
status	enum	active o inactive.
allowed_recipients	string[]	Cuando no está vacío, solo se aprueban los correos cuyo to incluya una de estas direcciones. Se soportan wildcards (*@acme.com).
filters	JSON	Array de reglas de filtro (ver abajo).
attachments_allow	bool	Si se permiten adjuntos en absoluto.
attachments_max_file_number	int	Máx. de adjuntos por correo. Default 10.
attachments_max_file_size	int	Bytes. Default 10485760 (10 MiB).
attachments_max_total_size	int	Bytes. Default 41943040 (40 MiB).
attachments_allow_rules	array|null	Lista de adjuntos permitidos. null procesa todos los adjuntos. Ver Reglas de adjuntos permitidos.
custom_metadata	object	Formato libre.
metadata	object	Controlado por el sistema.
created_at / updated_at / deleted_at	datetime

Filtros

El campo filters es un array JSON. Cada elemento es una regla como:

{ "field": "from", "op": "matches", "value": "^.*@acme\\.com$" }

field	op	value
from, subject, header.<name>	equals, contains, matches (regex)	string
headers.list-id	present, absent	(sin valor)
body.text	contains	string

Las reglas se combinan con AND. Si alguna regla falla, el correo se rechaza con rejection_reason=filters.

Reglas de adjuntos permitidos

attachments_allow_rules decide qué adjuntos de un correo se procesan. Cada regla puede tener:

Clave	Tipo	Significado
extensions	string[]	Extensiones sin el punto, sin distinguir mayúsculas: ["pdf", "xml"].
filename_pattern	string	Expresión regular JavaScript evaluada contra el nombre del archivo, hasta 200 caracteres: ^GUIA_. Los cuantificadores anidados se rechazan.
case_sensitive	bool	Aplica a filename_pattern. Por defecto false.

Una regla necesita extensions, filename_pattern o ambos; dentro de una regla, todas las claves indicadas deben cumplirse. Un adjunto se procesa cuando cumple cualquier regla. Hasta 20 reglas.

[{ "extensions": ["pdf"], "filename_pattern": "^GUIA_" }]

procesa solo los PDF cuyo nombre empieza con GUIA_ (sin distinguir mayúsculas).

Un adjunto fuera de la lista se ignora, nunca es motivo para rechazar el correo:

• el agente no lo ve — los demás adjuntos mantienen su número (Anexo 1, Anexo 3);
• los attachments_max_* cuentan solo los adjuntos que pasaron;
• un paso de workflow que lo referencia (${{email.attachments.N}}) falla antes de enviar cualquier solicitud;
• el correo lo registra en metadata.ignoredAttachments, como { "index": N, "reason": "not_allowed" } (desde 0, el N de ${{email.attachments.N}}). Un reprocesamiento rehace la lista con las reglas actuales; cuando rechaza el correo, la clave se elimina.

Un adjunto sin nombre (el logo inline de una firma, por ejemplo) nunca cumple una regla. Cuando ningún adjunto pasa, el agente se ejecuta igual sobre el cuerpo. null o [] procesa todos los adjuntos.

Ejemplo

{
  "id": "b3c4d5e6-7a89-4b0c-9d1e-2f3a4b5c6d7e",
  "external_id": "00000000-0000-0000-0000-00000000001a",
  "workspace_id": "a8b2c1d4-9e7f-4a3b-8c5d-1f2e3a4b5c6d",
  "agent_id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
  "label": "Support — Triage",
  "email": "triage-3f4a@inbox.kobana.com.br",
  "status": "active",
  "allowed_recipients": ["support@acme.com"],
  "filters": [{ "field": "from", "op": "matches", "value": ".*@(acme|partner)\\.com$" }],
  "attachments_allow": true,
  "attachments_max_file_number": 10,
  "attachments_max_file_size": 10485760,
  "attachments_max_total_size": 41943040,
  "attachments_allow_rules": null,
  "custom_metadata": { "team": "support" },
  "metadata": {},
  "created_at": "2026-01-04T12:00:00.000Z",
  "updated_at": "2026-01-04T12:00:00.000Z",
  "deleted_at": null
}

Ciclo de vida

• POST /inboxes — crea (sin efectos secundarios en AWS).
• PATCH /inboxes/{id} — actualiza label, filtros, destinatarios permitidos, política de adjuntos, agente asociado.
• DELETE /inboxes/{id} — soft-delete. Los correos futuros a la dirección se rechazan con recipient_unknown.

Establecer status: "inactive" mantiene la fila pero rechaza nuevos correos con recipient_unknown — útil para suspensiones temporales en las que planeas reactivar.