Introdução

Inbox Autônomo é um serviço que recebe, armazena, filtra e processa e-mails de entrada em nome dos produtos internos da Kobana. O e-mail chega via AWS SES, é persistido no S3 e no Postgres, opcionalmente processado por um agente LLM, e exposto através de uma API REST pública e webhooks.

A API é REST sobre HTTPS, com JSON e autenticação mTLS + Bearer JWT. Tudo que a plataforma faz com workspaces, inboxes, e-mails, agents e webhooks está disponível para seus sistemas, sob o mesmo isolamento por workspace do próprio produto.

Primeiros passos

1. Obtenha um certificado cliente e um JWT para o ambiente alvo — veja Autenticação.

2. Faça sua primeira chamada:

   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. Explore os recursos — a categoria Resources no menu lateral documenta todos os endpoints com exemplos. Ou importe a especificação OpenAPI / a collection do Postman.

Formato

A API aceita e retorna somente JSON. Toda requisição deve usar Content-Type: application/json. Todas as respostas usam snake_case.

Tipo de campo	Formato
DateTime	ISO 8601 em UTC com precisão de milissegundos. Exemplo: 2026-05-17T12:34:56.789Z
UUID	Identificadores de recursos são UUID v4

Convenções usadas nesta documentação

Convenção	Significado
{id}	Variável de path a ser substituída em uma URL.
...	Conteúdo de resposta truncado para legibilidade.
$JWT	Seu Bearer token. Para testar via linha de comando, exporte-o: export JWT=xxxxxxxxxxxxxxxxxxxxxxxx e cole os comandos desta documentação no seu terminal.

Status codes

A API retorna códigos HTTP padrão:

	Código	Significado
✅	200 OK	Requisição bem-sucedida com corpo de resposta.
✅	201 Created	Recurso criado com sucesso.
✅	202 Accepted	Requisição aceita para processamento assíncrono.
✅	204 No Content	Requisição bem-sucedida, sem corpo de resposta.
❌	400 Bad Request	Requisição malformada.
❌	401 Unauthorized	Certificado cliente / JWT ausente ou inválido.
❌	403 Forbidden	Autenticado, mas sem o scope exigido.
❌	404 Not Found	Recurso não existe, ou pertence a outro workspace.
❌	409 Conflict	Conflito de estado — ex.: external_id já em uso, X-Idempotency-Key reutilizada com um body diferente.
❌	422 Unprocessable Entity	Requisição bem-formada, dados inválidos.
❌	429 Too Many Requests	Limite de requisições excedido.
❌	500 Internal Server Error	Erro não tratado. Veja status do servidor.

O envelope de erro e o vocabulário estável de códigos de erro estão documentados em Erros.

Correlação de requisições

Toda resposta — bem-sucedida ou não — carrega um header X-Request-Id. Inclua-o ao reportar problemas para que o time Kobana possa buscar o trace no OpenTelemetry.

Próximos passos

• Autenticação — mTLS, JWT, scopes.
• Endpoints — os hosts da API e da documentação.
• OpenAPI — spec OpenAPI 3.1 para download ou ao vivo.
• User-Agent — header para identificar sua integração.
• Limite de requisições — throttling e headers de resposta.
• Paginação — paginação por cursor e o envelope de listagem.
• Filtros e ordenação — gramática de query parameters.
• Idempotência — X-Idempotency-Key para retries seguros.
• Erros — envelope de erro e vocabulário de códigos.
• Retenção de dados — política de retenção por recurso.