Mailgun

Mailgun es un servicio de correo transaccional orientado a desarrolladores. Es una opción sólida por defecto para Frontmail: una API sencilla, regiones en EE. UU. y la UE, datos de eventos detallados y webhooks de entrega, rebotes, quejas, aperturas y clics.

Elige Mailgun si envías correo transaccional (registros, recibos, notificaciones, envíos de formularios) desde tu propio dominio, quieres seguir rebotes y quejas y prefieres mantener los datos en la UE (región UE de Mailgun). Para unos pocos correos desde un buzón personal, SMTP o Gmail son más sencillos. Consulta el resumen de los servicios para compararlos.

Requisitos previos

Una cuenta de Mailgun. Las cuentas nuevas empiezan con un dominio sandbox que solo puede enviar a destinatarios autorizados (consulta Sandbox y límites).
Un dominio de envío añadido y verificado en Mailgun; te recomendamos un subdominio como mg.example.com, para que la reputación y el DNS de tu dominio principal queden separados.
Una clave de API. Crea una clave dedicada para Frontmail en Account settings → API security → Add new key (en la interfaz antigua: Account → API keys).
- Usa una clave con el rol más restrictivo que aún permita enviar y leer la información del dominio (p. ej. Developer en lugar de Admin).
- Una domain sending key (Sending → Domain settings → Sending API keys) puede enviar, pero no leer el dominio, así que Probar conexión y la comprobación de estado diaria la darán por rota. Usa una clave privada de la cuenta.
Opcional: la HTTP webhook signing key de Sending → Webhooks para los eventos de entrega.

Conectar en Frontmail

Abre Servicios de correo → Añadir servicio → Mailgun.
Rellena los campos:

Campo	Dónde encontrarlo	Ejemplo
Región	La región que aparece junto al dominio en Mailgun (Sending → Domains)	`UE (api.eu.mailgun.net)`
Dominio de envío	Sending → Domains, exactamente como aparece	`mg.example.com`
Clave de API	Account settings → API security (se muestra una sola vez al crearla)	`key-3ax6…` / `a1b2c3…-us`
Clave de firma de webhooks	Sending → Webhooks → HTTP webhook signing key	`8c1f…`
Máx. de correos por segundo	Opcional; por defecto 10/s	`5`

Haz clic en Verificar y guardar: Frontmail llama a la API de Mailgun para el dominio y comprueba que la clave, la región y el dominio coinciden.
El servicio se guarda cuando la comprobación es correcta. Las credenciales se cifran con cifrado de sobre de AWS KMS; solo el proceso de envío las descifra al enviar.

La dirección From de la plantilla debe estar en el dominio de envío (p. ej. hello@mg.example.com), o en el dominio principal si es el que verificaste.

DNS: SPF, DKIM y DMARC

Mailgun muestra los registros exactos de tu dominio en Sending → Domains → DNS records. Para mg.example.com tienen este aspecto:

; SPF
mg.example.com.                     TXT    "v=spf1 include:mailgun.org ~all"

; DKIM: el selector se genera para cada dominio (p. ej. pic, k1, smtp, mx)
pic._domainkey.mg.example.com.      TXT    "k=rsa; p=MIGfMA0GCSqGSIb3DQEB…"

; Recepción / gestión de rebotes (recomendado)
mg.example.com.                     MX 10  mxa.mailgun.org.
mg.example.com.                     MX 10  mxb.mailgun.org.     ; UE: mxa.eu.mailgun.org / mxb.eu.mailgun.org

; Seguimiento de aperturas y clics
email.mg.example.com.               CNAME  mailgun.org.         ; UE: eu.mailgun.org

; DMARC: en el dominio organizativo, empieza con supervisión
_dmarc.example.com.                 TXT    "v=DMARC1; p=none; rua=mailto:dmarc@example.com"

Copia el selector DKIM desde Mailgun, no desde este ejemplo: cambia en cada dominio (pic._domainkey, k1._domainkey, …). Los dominios más recientes también pueden usar DKIM delegado mediante CNAME con rotación automática de claves.
Si el dominio principal ya tiene SPF para tu buzón, no pasa nada: el subdominio tiene su propio registro SPF.
Haz clic en Verify DNS settings en Mailgun; la propagación puede tardar de minutos a horas.
Cuando los informes de DMARC estén limpios, endurécelo a p=quarantine y más adelante a p=reject.

Regiones

Mailgun funciona en dos regiones totalmente separadas:

Región	Host de la API	Úsala cuando
EE. UU.	`api.mailgun.net`	el dominio se creó en la región de EE. UU. (predeterminada)
UE	`api.eu.mailgun.net`	el dominio se creó en la región de la UE (los datos se quedan en la UE)

Un dominio existe en una sola región, así que elige la región en la que se creó el dominio. Si no coinciden, se devuelve 404 Domain not found, que Frontmail trata como un error de auth. La región no se puede cambiar después: para trasladarte, vuelve a añadir el dominio en la otra región.

Sandbox y límites

Dominio sandbox (sandbox123….mailgun.org): envía solo a destinatarios autorizados (hasta 5) que hayan confirmado un correo de invitación. Cualquier otro envío falla con «Free accounts are for test purposes only». Sirve para una primera prueba, no para producción.
Plan gratuito: unos 100 correos al día.
Cuentas o dominios nuevos: Mailgun puede limitar su velocidad hasta que acumules historial de envíos o completes la verificación de la empresa.
La velocidad predeterminada de Frontmail para Mailgun es de 10 mensajes por segundo por servicio; bájala en Máx. de correos por segundo si Mailgun te limita.

Webhooks (seguimiento de la entrega)

Mailgun puede informar de lo que pasó después de aceptar un mensaje.

Copia la URL del webhook de la página del servicio en Frontmail (botón de copiar junto a URL del webhook). Tiene este aspecto:
```
https://api.frontmail.dev/webhooks/providers/mailgun/<token>
```
<token> es único para este servicio: no lo compartas entre servicios.
En Mailgun, abre Sending → Webhooks, elige el dominio (y la región) correctos y añade la URL para estos eventos:

Evento de Mailgun	Evento de Frontmail
Delivered	`delivered`
Permanent failure	`bounced`: la dirección se añade a la lista de supresión
Temporary failure	se registra en el mensaje; Mailgun sigue reintentando
Spam complaints	`complained`: se añade a la lista de supresión
Opens	`opened` (requiere el seguimiento de aperturas en el dominio)
Clicks	`clicked` (requiere el seguimiento de clics en el dominio)

Copia la HTTP webhook signing key de la misma página en el campo Clave de firma de webhooks del servicio en Frontmail.

Verificación de la firma: cada webhook de Mailgun incluye timestamp, token y signature. Frontmail calcula el HMAC-SHA256 de timestamp + token con tu clave de firma y rechaza las solicitudes cuya firma no coincide. Sin la clave de firma, los eventos no se pueden verificar y se ignoran.

Frontmail etiqueta cada mensaje con v:frontmail_message_id, así que los eventos se asocian al mensaje correcto aunque envíes la misma plantilla muchas veces.

Errores habituales

Frontmail clasifica los errores del proveedor en tres clases:

auth: el servicio no funciona (clave de API no válida, 401/403, dominio o región incorrectos, restricciones del sandbox). El servicio se marca como unhealthy y el propietario recibe un correo y un aviso en el panel. Si la plantilla tiene un servicio de respaldo, el mensaje sale por él; si no, se devuelve el crédito y el mensaje espera en la cola de correos retenidos como held_service_error, para enviarse automáticamente cuando arregles el servicio (se vuelve a comprobar al guardar y en la comprobación de estado diaria).
permanent: este mensaje no se puede enviar (destinatario no válido, error de validación 4xx). Se prueba el servicio de respaldo si está configurado; si no, el estado es failed y se devuelve el crédito.
transient: tiempos de espera agotados, 5xx, limitación 429. Se reintenta con espera exponencial; cuando se agotan los reintentos, el mensaje pasa a failed y se devuelve el crédito.

Respuesta de Mailgun	Clase	Qué hacer
`401 Forbidden`	auth	La clave de API es incorrecta, se ha eliminado o pertenece a otra cuenta. Crea una clave nueva y actualiza el servicio.
`404 Domain not found: mg.example.com`	auth	Revisa cómo está escrito el dominio y la Región (los dominios de la UE necesitan `api.eu.mailgun.net`).
`400 Domain mg.example.com is not allowed to send: Free accounts are for test purposes only…`	auth	Dominio sandbox o cuenta sin verificar: añade un destinatario autorizado, verifica tu propio dominio o mejora el plan.
`403` «account disabled / domain disabled»	auth	Mailgun ha suspendido el envío; revisa el panel de Mailgun y contacta con su soporte.
`400 'to' parameter is not a valid address`	permanent	La dirección del destinatario está mal formada; consulta destinatario no válido.
`413 Request Entity Too Large`	permanent	El mensaje con adjuntos supera el límite de tamaño de Mailgun (25 MB).
`429 Too Many Requests`	transient	Limitación; Frontmail respeta `Retry-After`. Baja Máx. de correos por segundo si ocurre a menudo.
`500` / `502` / `503`, tiempo de espera agotado	transient	Caída de Mailgun: no tienes que hacer nada, Frontmail reintenta.

Lista de comprobación

Dominio de envío propio (p. ej. mg.example.com) añadido y verificado en Mailgun
SPF, DKIM, MX y CNAME de seguimiento publicados; DMARC al menos p=none
La Región en Frontmail coincide con la región del dominio
Clave de API privada con un rol restringido, no una domain sending key
Probar conexión funciona
URL del webhook añadida para delivered, permanent failure y complaints (+ opens/clicks si hace falta)
Clave de firma de webhooks copiada en Frontmail
La dirección From de la plantilla está en el dominio verificado