> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de caixas de entrada de correio

> Referência interna para a API Mail Inboxes — CRUD de caixa de entrada, gerenciamento de endereço de encaminhamento, atribuição de IA e processamento de e-mail de entrada.

> **Documentação interna para desenvolvedores.** Esta página aborda a API Mail Inboxes: criação, atribuição de IA, gerenciamento de alias, contagens de não lidas e roteamento de e-mails recebidos. Não se destina a usuários finais.

***

## Mapa de rotas

| Método   | Ponto final                                  | Arquivo manipulador                              | Descrição                                           |
| -------- | -------------------------------------------- | ------------------------------------------------ | --------------------------------------------------- |
| `GET`    | `/api/mail-inboxes`                          | `mail-inboxes/route.ts`                          | Listar todas as caixas de entrada de e-mail         |
| `POST`   | `/api/mail-inboxes`                          | `mail-inboxes/route.ts`                          | Crie uma caixa de entrada de e-mail                 |
| `GET`    | `/api/mail-inboxes/[id]`                     | `mail-inboxes/[id]/route.ts`                     | Receba inbox por ID                                 |
| `PATCH`  | `/api/mail-inboxes/[id]`                     | `mail-inboxes/[id]/route.ts`                     | Atualizar caixa de entrada (nome, IA, conhecimento) |
| `DELETE` | `/api/mail-inboxes/[id]`                     | `mail-inboxes/[id]/route.ts`                     | Excluir caixa de entrada                            |
| `GET`    | `/api/mail-inboxes/unread`                   | `mail-inboxes/unread/route.ts`                   | Obtenha contagens não lidas por caixa de entrada    |
| `POST`   | `/api/mail-inboxes/check-alias-availability` | `mail-inboxes/check-alias-availability/route.ts` | Validar alias de e-mail                             |

***

## Padrão de autenticação

```ts theme={null}
withPermissionRoute(req, {
  anyPermission: ['mail_inboxes.read'],  // reads
  anyPermission: ['mail_inboxes.manage'], // mutations
  authMode: 'lightweight',               // reads only
}, handler)
```

***

## Esquema de objeto de caixa de entrada

```ts theme={null}
interface MailInbox {
  id: string;
  organizationId: string;
  name: string;
  alias: string;           // e.g., "a1b2c3d4" → a1b2c3d4@mail.zappway.ai
  agentId: string | null;  // assigned AI Employee
  aiEnabled: boolean;      // whether AI auto-responds
  datastoreIds: string[];  // connected knowledge
  datasourceIds: string[]; // connected knowledge
  createdAt: string;
  updatedAt: string;
}
```

***

## Geração de Alias

Quando uma nova caixa de entrada é criada, um alias exclusivo é gerado:

```ts theme={null}
// Format: {randomHex}@mail.zappway.ai
// Stored in: mail_inbox.alias
// Inbound emails sent to this address are processed by the inbox
```

**Verificação de disponibilidade do alias:**
***CÓDIGO\_BLOCO\_3***

***

## Atribuição de IA

```ts theme={null}
// PATCH /api/mail-inboxes/[id]
// Body: {
//   aiEnabled: true,
//   agentId: 'agent_123',
//   datastoreIds: ['ds_abc'],
//   datasourceIds: ['dsc_xyz'],
// }
```

Quando `aiEnabled: true` e `agentId` estão definidos, cada e-mail recebido aciona o Funcionário de IA para gerar uma resposta.

***

## Fluxo de processamento de e-mail de entrada

```
Email → Forwarded to {alias}@mail.zappway.ai
     ↓
ZappWay email receiving service (MX records)
     ↓
POST to internal webhook (not public API)
     ↓
Lookup inbox by alias
     ↓
Create contact (if new sender)
Create conversation (channel: 'email')
     ↓
If aiEnabled + agentId: trigger AI response
If aiEnabled + no agentId: queue for human
     ↓
AI response → sent via transactional email service
```

***

## Contagens não lidas

```ts theme={null}
// GET /api/mail-inboxes/unread
// Returns: { [inboxId]: number }
// Used by sidebar badge indicator
// authMode: 'lightweight' for performance
```

***

## Índices Prisma usados

| Tabela      | Índice           | Usado por                         |
| ----------- | ---------------- | --------------------------------- |
| `MailInbox` | `organizationId` | Listar caixas de entrada          |
| `MailInbox` | `alias` (único)  | Pesquisa de roteamento de entrada |
| `MailInbox` | `agentId`        | Consultas de atribuição de agente |

***

## Problemas conhecidos/pegadinhas

* **Exclusividade do alias:** `alias` deve ser globalmente exclusivo em TODAS as organizações (não apenas dentro de uma organização). A restrição do banco de dados é global.
* **Excluir uma caixa de entrada:** A exclusão não revoga o alias de e-mail imediatamente — os e-mails enviados para um alias excluído serão devolvidos. Considere um período de carência ou exclusão reversível.
* **Remetente de resposta de IA:** Os e-mails são enviados DE `{alias}@mail.zappway.ai`, não do domínio do cliente. Esta é uma limitação conhecida mencionada nos documentos do usuário.
* **Acesso à fonte de conhecimento:** `datastoreIds` e `datasourceIds` devem pertencer à mesma organização. O acesso ao conhecimento entre organizações é bloqueado pela camada de permissão.