> ## 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 bandejas de entrada de correo

> Referencia interna para la API de Mail Inboxes: CRUD de la bandeja de entrada, administración de direcciones de reenvío, asignación de IA y procesamiento de correo electrónico entrante.

> **Documentación interna para desarrolladores.** Esta página cubre la API de bandejas de entrada de correo: creación, asignación de IA, administración de alias, recuentos de no leídos y enrutamiento de correo electrónico entrante. No está destinado a usuarios finales.

***

## Mapa de ruta

| Método   | Punto final                                  | Archivo de controlador                           | Descripción                                              |
| -------- | -------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------- |
| `GET`    | `/api/mail-inboxes`                          | `mail-inboxes/route.ts`                          | Listar todas las bandejas de entrada de correo           |
| `POST`   | `/api/mail-inboxes`                          | `mail-inboxes/route.ts`                          | Crear una bandeja de entrada de correo                   |
| `GET`    | `/api/mail-inboxes/[id]`                     | `mail-inboxes/[id]/route.ts`                     | Recibir inbox por ID                                     |
| `PATCH`  | `/api/mail-inboxes/[id]`                     | `mail-inboxes/[id]/route.ts`                     | Actualizar bandeja de entrada (nombre, IA, conocimiento) |
| `DELETE` | `/api/mail-inboxes/[id]`                     | `mail-inboxes/[id]/route.ts`                     | Eliminar bandeja de entrada                              |
| `GET`    | `/api/mail-inboxes/unread`                   | `mail-inboxes/unread/route.ts`                   | Obtener recuentos de no leídos por bandeja de entrada    |
| `POST`   | `/api/mail-inboxes/check-alias-availability` | `mail-inboxes/check-alias-availability/route.ts` | Validar alias de correo electrónico                      |

***

## Patrón de autenticación

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

***

## Esquema de objetos de la bandeja 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;
}
```

***

## Generación de alias

Cuando se crea una nueva bandeja de entrada, se genera un alias único:

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

**Verificación de disponibilidad de alias:**
***CÓDIGO\_BLOQUE\_3***

***

## Asignación de IA

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

Cuando se configuran `aiEnabled: true` y ​​`agentId`, cada correo electrónico entrante hace que el empleado de IA genere una respuesta.

***

## Flujo de procesamiento de correo electrónico entrante

```
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
```

***

## Recuentos no leídos

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

***

## Índices Prisma utilizados

| Mesa        | Índice           | Utilizado por                      |
| ----------- | ---------------- | ---------------------------------- |
| `MailInbox` | `organizationId` | Listar bandejas de entrada         |
| `MailInbox` | `alias` (único)  | Búsqueda de rutas entrantes        |
| `MailInbox` | `agentId`        | Consultas de asignación de agentes |

***

## Problemas conocidos / Problemas

* **Unicidad de alias:** `alias` debe ser globalmente único en TODAS las organizaciones (no solo dentro de una organización). La restricción de la base de datos es global.
* **Eliminar una bandeja de entrada:** La eliminación no revoca el alias de correo electrónico inmediatamente; los correos electrónicos enviados a un alias eliminado rebotarán. Considere un período de gracia o una eliminación temporal.
* **Remitente de respuesta AI:** Los correos electrónicos se envían DESDE `{alias}@mail.zappway.ai`, no desde el dominio del cliente. Esta es una limitación conocida mencionada en los documentos de usuario.
* **Acceso a la fuente de conocimiento:** `datastoreIds` y ​​`datasourceIds` deben pertenecer a la misma organización. El acceso al conocimiento entre organizaciones está bloqueado por la capa de permiso.