API de correo

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

Categoría: Comunicación
Estado: Disponible
Requisitos: Al menos una cuenta 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>.

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

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

Envío por API

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.

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`