> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axelo.mx/llms.txt
> Use this file to discover all available pages before exploring further.
# Email transaccional
> Envía emails HTML personalizados usando plantillas visuales.
## Cómo funciona
El canal de email usa **Postfix** como MTA con autenticación de dominio completa:
* **SPF** — el IP del servidor está autorizado para enviar en nombre del dominio
* **DKIM** — cada email lleva firma criptográfica
* **DMARC** — política de autenticación publicada en DNS
Tienes **dos formas** de definir el contenido de un email:
1. **Plantilla registrada** (`template_id`) — creas el HTML una vez en el dashboard y lo reutilizas.
2. **HTML inline** (`html`) — envías el HTML completo en el propio request, sin registrar plantilla.
En ambos casos el HTML se combina con el objeto `data` usando sintaxis de Go templates (`{{.variable}}`).
## Crear una plantilla
Desde el dashboard de tu cuenta (`/app/me`):
1. Ve a **Email Templates**
2. Crea una nueva plantilla con el editor visual
3. Declara las variables que usarás en el panel "Variables" del editor
4. Guarda — el `template_id` es el slug que usarás en la API
## Enviar un email
```bash theme={null}
curl -X POST https://api.axelo.mx/v1/send/email \
-H "Content-Type: application/json" \
-H "X-API-Key: TU_API_KEY" \
-d '{
"to_address": "juan@ejemplo.com",
"to_name": "Juan Pérez",
"subject": "Tu pedido {{.numero}} está listo",
"template_id": "pedido-listo",
"data": {
"numero": "ORD-4521",
"fecha": "28 de marzo de 2026"
}
}'
```
### Parámetros
| Campo | Tipo | Requerido | Descripción |
| ------------- | ------ | ----------- | ------------------------------------------------------------------------------------- |
| `to_address` | string | ✅ | Dirección de destino |
| `to_name` | string | — | Nombre del destinatario |
| `subject` | string | — | Asunto (soporta variables). Si se omite, usa el subject de la plantilla |
| `template_id` | string | Condicional | ID de la plantilla HTML. Requerido si **no** envías `html` |
| `html` | string | Condicional | HTML crudo inline (alternativa a `template_id`). Requiere el permiso `allow_raw_html` |
| `data` | object | — | Variables para inyectar en el HTML y el subject |
Envía **`template_id` o `html`**, no ambos. Si mandas los dos, `html` tiene precedencia.
## Enviar HTML inline (sin plantilla)
Si prefieres generar el HTML desde tu propia plataforma, mándalo directo en el campo `html`:
```bash theme={null}
curl -X POST https://api.axelo.mx/v1/send/email \
-H "Content-Type: application/json" \
-H "X-API-Key: TU_API_KEY" \
-d '{
"to_address": "juan@ejemplo.com",
"subject": "Hola {{.nombre}}",
"html": "Hola {{.nombre}}
Tu pedido va en camino.
",
"data": { "nombre": "Juan" }
}'
```
Como el HTML crudo tiene mayor impacto en la reputación de entrega (se envía sobre infraestructura
compartida), esta capacidad está protegida. Implicaciones a tener en cuenta:
* **Requiere permiso.** El campo `html` solo funciona si tu tenant tiene habilitado `allow_raw_html`
(lo activa tu proveedor). Si no, la API responde `403`. Las plantillas registradas (`template_id`)
no requieren este permiso.
* **Validación de contenido.** Antes de encolar se corren heurísticas: HTML vacío, demasiado grande
(>512 KB), solo-imagen (sin texto) o con `