# API de correo

Enviar y leer correo desde un programa con una llave `am_`, a través de una cola con turnos por empresa.

Fuente: https://ardumaker.com/docs/email-api/

- Categoría: Comunicación
- Estado: Disponible
- Requisitos: Al menos una [cuenta bot](https://ardumaker.com/docs/cuentas-bot) en un dominio verificado; Ser admin de la empresa para crear llaves
- Herramientas MCP (Solo leen): `ver_api_correo`, `listar_api_keys_correo`, `ver_cola_correo`
- Herramientas MCP (Escriben o modifican): `crear_api_key_correo`
- Herramientas MCP (Destructivas): `cambiar_token_api_key_correo`, `revocar_api_key_correo`

## ¿Qué permite hacer?

- Enviar correo desde una cuenta bot con `POST /emails`.
- Consultar lo enviado y el estado de cada correo por su id.
- Leer lo que recibieron las cuentas bot con `GET /inbound`.
- Crear llaves con alcance a un dominio entero o a una lista de bots, con permiso completo o solo envío.

## ¿Cuándo conviene usarlo?

Para correo que dispara una aplicación: avisos, confirmaciones, respuestas automáticas o leer un buzón de entrada desde código.

## ¿Cómo funciona en ArduMaker?

Cada pedido lleva `Authorization: Bearer <llave am_...>`. El remitente (`from`) tiene que ser una cuenta bot que la llave alcance; se acepta también `Nombre <bot@dominio>`.

```bash
curl -X POST "$BASE/emails" \
  -H "Authorization: Bearer am_..." \
  -H "Content-Type: application/json" \
  -d '{"from":"avisos@tuempresa.com","to":"cliente@ejemplo.com","subject":"Hola","text":"Mensaje"}'
```

Enviar responde 202: el correo queda en cola, no enviado. La cola sale por turnos: un correo por empresa por vuelta, en orden de llegada, con un tope por empresa y un tope global por minuto. La URL base exacta la devuelve `ver_api_correo`.

| Límite | Valor |
| --- | --- |
| Destinatarios por correo | 50 |
| Adjuntos por correo (base64) | 10 MB |
| Correos en cola por empresa | 1000 |
| Envíos por minuto por empresa | 10 por defecto |
| Envíos por minuto en toda la plataforma | 20 por defecto |

## ¿Qué cambia realmente?

- Cada envío crea un registro en la cola con estado `queued`, `sending`, `sent` o `failed`.
- Lo enviado queda en la casilla de la cuenta bot, así que las respuestas llegan y se leen con la misma llave.
- Revocar una llave no la borra: queda apagada para que el historial siga sabiendo quién envió cada correo.

## Esquema

**Envío por API**

```text
Tu programa (llave am_)
  ↓
API de correo (valida remitente y límites)
  ↓
Cola de salida (turnos por empresa)
  ↓
Casilla de la cuenta bot (SMTP)
  ↓
Destinatario
```

## Resultado esperado

El programa recibe un id por correo y consulta su estado hasta `sent` o `failed`. Las respuestas de los destinatarios se leen desde la casilla de la cuenta bot.

## Errores y resolución

| Respuesta | Causa |
| --- | --- |
| 403 `remitente_no_permitido` | El `from` no es una cuenta bot que la llave alcance. |
| 429 `Queue is full` | La empresa ya tiene 1000 correos esperando. |
| 400 `adjunto_invalido` o `total_attachment_size` | Adjunto mal codificado o por encima de 10 MB. |
| 424 `casilla_no_lista` | La cuenta bot no tiene su casilla lista en el servidor. |

Un correo `failed` no se reintenta solo. `ver_cola_correo` muestra cuántos esperan, cuánto lleva el más viejo y el error de los últimos.

## Relación con MCP

Las llaves se administran por MCP y solo un admin de la empresa puede crearlas, renovarlas o revocarlas. Ver [/mcp/correo](https://ardumaker.com/mcp/correo).

| Tipo | Herramientas |
| --- | --- |
| Lectura | `ver_api_correo`, `listar_api_keys_correo`, `ver_cola_correo` |
| Modifican | `crear_api_key_correo`, `cambiar_token_api_key_correo` |
| Destructiva | `revocar_api_key_correo` |

> **PRECAUCION:** El token de una llave se muestra una sola vez, al crearla o renovarla. Renovar invalida el anterior.

## Funciones relacionadas

- [Cuentas bot](https://ardumaker.com/docs/cuentas-bot/)
- [Correo profesional](https://ardumaker.com/docs/correo-profesional/)
- [SMTP e IMAP](https://ardumaker.com/docs/smtp-imap/)
- [Notificaciones](https://ardumaker.com/docs/notificaciones/)