Inboxes

Un inbox es una dirección de recepción más las reglas que se aplican al correo que llega a ella. Ocho tools, incluidas las dos que gestionan la lista de remitentes permitidos.

Ver el modelo Inbox para la forma del objeto devuelto.

---

inboxes_list

Lectura · scope inbox/inboxes · permiso inboxes.list · GET /inboxes

Lista los inboxes del workspace seleccionado. Paginado por cursor.

Parámetro	Tipo	Descripción
cursor	string	Cursor opaco de una página anterior.
limit	integer	Tamaño de página, por defecto 25, máximo 100.
sort	string	Claves de ordenación, prefijo - para descendente.
status	active | inactive	Filtra por estado.
agent_id	string (uuid)	Solo inboxes ligados a este agente.
slug	string	Filtra por slug.
email	string	Filtra por la dirección de recepción.
external_id	string	Filtra por el id en tu sistema.
created_at_gte	string	created_at desde este timestamp ISO 8601.
created_at_lte	string	created_at hasta este timestamp ISO 8601.

inboxes_get

Lectura · scope inbox/inboxes · permiso inboxes.show · GET /inboxes/{id}

Obtiene un inbox por id interno o external_id.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.

inboxes_create

Escritura · scope inbox/inboxes + write · permiso inboxes.create · POST /inboxes

Crea un inbox. La dirección de recepción se compone en el servidor como {organization}.{workspace}.{inbox}@<dominio> y queda activa de inmediato — no interviene ninguna llamada a AWS. 409 si el slug colisiona en el mismo workspace, 422 cuando la parte local compuesta supera 64 caracteres.

Parámetro	Tipo	Descripción
label obligatorio	string	Nombre visible, 1–120 caracteres.
slug	string	Minúsculas, con guiones, hasta 20 caracteres. Último segmento de la dirección de recepción; derivado del label cuando se omite.
external_id	string	Id del registro en tu sistema.
agent_id	string (uuid) | null	Agente que procesa el correo de este inbox.
allowed_recipients	string[]	Cuando se define, solo se acepta correo cuyo remitente de sobre esté en esta lista.
filters	object[]	Reglas de aceptación aplicadas al correo entrante.
attachments_allow	boolean	Si se aceptan adjuntos.
attachments_max_file_number	integer	Número máximo de adjuntos.
attachments_max_file_size	integer	Tamaño máximo por adjunto, en bytes.
attachments_max_total_size	integer	Tamaño total máximo de adjuntos, en bytes.
attachments_allow_rules	array|null	Lista de adjuntos permitidos; cada regla necesita extensions, filename_pattern o ambos — ver reglas de adjuntos permitidos. null la limpia.
custom_metadata	object	JSON libre, de quien llama.
idempotency_key	string	Protección contra repeticiones, 8–255 caracteres.

inboxes_upsert

Escritura · scope inbox/inboxes + write · permiso inboxes.create · PUT /inboxes

Crea o actualiza un inbox, emparejado por id, luego external_id, luego email. Los campos omitidos conservan su valor almacenado.

Parámetro	Tipo	Descripción
id	string (uuid)	Empareja primero por id interno.
email	string	Empareja por dirección de recepción, después de id y external_id.
label	string	Nombre visible, 1–120 caracteres.
slug	string	Minúsculas, con guiones, hasta 20 caracteres.
external_id	string	Clave de emparejamiento en tu sistema.
agent_id	string (uuid) | null	Agente que procesa el correo de este inbox.
allowed_recipients	string[]	Remitentes de sobre aceptados.
filters	object[]	Reglas de aceptación.
attachments_allow	boolean	Si se aceptan adjuntos.
attachments_max_file_number	integer	Número máximo de adjuntos.
attachments_max_file_size	integer	Tamaño máximo por adjunto, en bytes.
attachments_max_total_size	integer	Tamaño total máximo de adjuntos, en bytes.
attachments_allow_rules	array|null	Lista de adjuntos permitidos; cada regla necesita extensions, filename_pattern o ambos — ver reglas de adjuntos permitidos. null la limpia.
custom_metadata	object	JSON libre.
idempotency_key	string	Protección contra repeticiones.

inboxes_update

Escritura · scope inbox/inboxes + write · permiso inboxes.update · PATCH /inboxes/{id}

Actualiza un inbox. Cambiar el slug reapunta la dirección de recepción — el correo enviado a la anterior deja de llegar. Los cambios de filtro se aplican solo al correo futuro.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.
label	string	Nombre visible, 1–120 caracteres.
slug	string	Minúsculas, con guiones, hasta 20 caracteres.
external_id	string	Id en tu sistema.
agent_id	string (uuid) | null	Agente que procesa el correo de este inbox.
allowed_recipients	string[]	Remitentes de sobre aceptados.
filters	object[]	Reglas de aceptación.
attachments_allow	boolean	Si se aceptan adjuntos.
attachments_max_file_number	integer	Número máximo de adjuntos.
attachments_max_file_size	integer	Tamaño máximo por adjunto, en bytes.
attachments_max_total_size	integer	Tamaño total máximo de adjuntos, en bytes.
attachments_allow_rules	array|null	Lista de adjuntos permitidos; cada regla necesita extensions, filename_pattern o ambos — ver reglas de adjuntos permitidos. null la limpia.
custom_metadata	object	JSON libre.

inboxes_delete

Destructiva · scope inbox/inboxes + write · permiso inboxes.delete · DELETE /inboxes/{id}

Elimina (soft-delete) un inbox. El correo entrante para esa dirección pasa a ser recipient_unknown; el slug se libera y puede reutilizarse.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.

inboxes_add_recipient

Destructiva · scope inbox/inboxes + write · permiso inboxes.update · POST /inboxes/{id}/recipients

Añade una dirección a allowed_recipients. Idempotente — 200 si ya estaba, 201 si es nueva.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.
email obligatorio	string	Dirección a permitir.

inboxes_remove_recipient

Destructiva · scope inbox/inboxes + write · permiso inboxes.update · DELETE /inboxes/{id}/recipients

Quita una dirección de allowed_recipients. 404 cuando la dirección no está en la lista.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.
email obligatorio	string	Dirección a quitar.