Introducción

Inbox Autónomo es un servicio que recibe, almacena, filtra y procesa correo entrante en nombre de los productos internos de Kobana. El correo llega vía AWS SES, se persiste en S3 y Postgres, opcionalmente se procesa mediante un agente LLM, y se expone a través de una API REST pública y de webhooks.

La API es REST sobre HTTPS, con JSON y autenticación mTLS + Bearer JWT. Todo lo que la plataforma hace con workspaces, inboxes, emails, agents y webhooks está disponible para tus sistemas, bajo el mismo aislamiento por workspace que el propio producto.

Primeros pasos

1. Obtén un certificado de cliente y un JWT para el entorno destino — ver Autenticación.

2. Realiza tu primera llamada:

   curl https://api.inbox.kobana.com.br/v1/workspaces?limit=1 \
     --cert ./client.crt --key ./client.key \
     -H "Authorization: Bearer $JWT" \
     -H "Accept: application/json"

3. Explora los recursos — la categoría Resources en la barra lateral documenta cada endpoint con ejemplos. O importa la especificación OpenAPI / la colección de Postman.

Formato

La API acepta y devuelve únicamente JSON. Todas las solicitudes deben usar Content-Type: application/json. Todas las respuestas usan snake_case.

Tipo de campo	Formato
DateTime	ISO 8601 en UTC con precisión de milisegundos. Ejemplo: 2026-05-17T12:34:56.789Z
UUID	Los identificadores de recurso son UUID v4

Convenciones usadas en esta documentación

Convención	Significado
{id}	Variable de path a reemplazar en una URL.
...	Contenido de la respuesta truncado por legibilidad.
$JWT	Tu token Bearer. Para pruebas por línea de comandos, expórtalo: export JWT=xxxxxxxxxxxxxxxxxxxxxxxx y pega los comandos de esta documentación en tu terminal.

Códigos de estado

La API devuelve códigos HTTP estándar:

	Código	Significado
✅	200 OK	Solicitud exitosa con cuerpo de respuesta.
✅	201 Created	Recurso creado exitosamente.
✅	202 Accepted	Solicitud aceptada para procesamiento asíncrono.
✅	204 No Content	Solicitud exitosa, sin cuerpo de respuesta.
❌	400 Bad Request	Solicitud malformada.
❌	401 Unauthorized	Certificado de cliente / JWT ausente o inválido.
❌	403 Forbidden	Autenticado pero sin el scope requerido.
❌	404 Not Found	El recurso no existe, o pertenece a otro workspace.
❌	409 Conflict	Conflicto de estado — p. ej. external_id ya en uso, X-Idempotency-Key reutilizada con un body diferente.
❌	422 Unprocessable Entity	Solicitud bien formada, datos inválidos.
❌	429 Too Many Requests	Límite de solicitudes excedido.
❌	500 Internal Server Error	Error no manejado. Ver estado del servidor.

El envelope de error y el vocabulario estable de códigos de error están documentados en Errores.

Correlación de solicitudes

Cada respuesta — exitosa o no — lleva un header X-Request-Id. Inclúyelo al reportar problemas para que el equipo de Kobana pueda obtener el trace desde OpenTelemetry.

Próximos pasos

• Autenticación — mTLS, JWT, scopes.
• Endpoints — los hosts de la API y de la documentación.
• OpenAPI — spec OpenAPI 3.1 para descargar o en vivo.
• User-Agent — header para identificar tu integración.
• Límite de solicitudes — throttling y headers de respuesta.
• Paginación — paginación por cursor y el envelope de listas.
• Filtros y ordenación — gramática de parámetros de query.
• Idempotencia — X-Idempotency-Key para reintentos seguros.
• Errores — envelope de error y vocabulario de códigos.
• Retención de datos — política de retención por recurso.