Email transaccional

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:

Plantilla registrada (template_id) — creas el HTML una vez en el dashboard y lo reutilizas.
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):

Ve a Email Templates
Crea una nueva plantilla con el editor visual
Declara las variables que usarás en el panel “Variables” del editor
Guarda — el template_id es el slug que usarás en la API

Enviar un email

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:

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":       "<html><body><h1>Hola {{.nombre}}</h1><p>Tu pedido va en camino.</p></body></html>",
    "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 <script> se rechaza de inmediato con 422 e incluye la lista de violations.
Filtro de spam. El mensaje se puntúa con un motor tipo SpamAssassin. Si supera el umbral, el job no se envía: queda en estado failed con el spam_score y las reglas disparadas (visible en Logs). No se te cobra por un email rechazado.

Consejo: manda siempre una versión con texto real (no solo imágenes), evita URLs acortadas y mantén una relación equilibrada texto/HTML. Puedes previsualizar tu puntaje en herramientas como mail-tester.com antes de automatizar envíos masivos.

Bajas (List-Unsubscribe)

Todos los emails — con plantilla o inline — incluyen automáticamente los headers List-Unsubscribe y one-click (RFC 8058) que Gmail y Yahoo exigen. Cuando un destinatario se da de baja (o su dirección rebota), se agrega a una lista de supresión por tenant y se omite en envíos futuros: esos jobs quedan con estado suppressed (sin envío ni cobro). No necesitas hacer nada para habilitarlo.

Variables

Las variables en data se inyectan con {{.NombreDeVariable}} tanto en el HTML como en el subject. Ver la guía de Variables en templates para más detalle.

Warm-up de IP

Si eres un tenant nuevo, los primeros días de envío desde una IP dedicada requieren una rampa gradual para construir reputación:

Semana 1–2: máximo 50–100 emails/día
Semana 3+: duplicar cada semana

Sin warm-up, los emails pueden llegar a spam. Contáctanos si necesitas orientación.

Primeros pasos

Canales

Conceptos

Email transaccional

Cómo funciona

Crear una plantilla

Enviar un email

Parámetros

Enviar HTML inline (sin plantilla)

Bajas (List-Unsubscribe)

Variables

Warm-up de IP

​Cómo funciona

​Crear una plantilla

​Enviar un email

​Parámetros

​Enviar HTML inline (sin plantilla)

​Bajas (List-Unsubscribe)

​Variables

​Warm-up de IP

Cómo funciona

Crear una plantilla

Enviar un email

Parámetros

Enviar HTML inline (sin plantilla)

Bajas (List-Unsubscribe)

Variables

Warm-up de IP