Integración domótica Mailgun, gratuita y de código abierto

Envíe las notificaciones de Gladys por correo con Mailgun y reaccione a las entregas.
Reciba sus notificaciones de Gladys por correo a través de Mailgun, envíe correos desde sus escenas e inicie escenas cuando un correo se entrega, falla, se abre o se pulsa un enlace.
Mailgun es un servicio en la nube: Gladys necesita acceso a Internet para enviar los correos.
Lo que necesita
- Una cuenta de Mailgun (el plan gratuito basta para empezar).
- Un dominio de envío en Mailgun, p. ej.
mg.ejemplo.es. El dominio «sandbox» que Mailgun crea para usted también funciona, pero solo envía a los «destinatarios autorizados» de su cuenta. - Una clave de API:
- una clave de envío del dominio (Mailgun → Sending → Domain settings → Sending keys) basta para enviar correos;
- la clave de API privada (Mailgun → API keys) es necesaria para las estadísticas del widget y para registrar los webhooks automáticamente.
- La región de su cuenta: EE. UU. (
api.mailgun.net) o UE (api.eu.mailgun.net). Un dominio creado en la región UE no existe para la API de EE. UU. - Opcional: Gladys Plus, para recibir los eventos de Mailgun (entregado, fallido, abierto…) e iniciar escenas con ellos.
Configuración
En Gladys: Integraciones → Mailgun → Configuración.
| Campo | Qué indicar |
|---|---|
| Clave de API de Mailgun | La clave de envío o la clave de API privada. |
| Dominio de envío | El dominio tal como aparece en Mailgun, p. ej. mg.ejemplo.es. |
| Región de la cuenta | EE. UU. o Europa. |
| Nombre del remitente | El nombre que se ve en la bandeja de entrada. Por defecto: Gladys. |
| Dirección del remitente | Una dirección del dominio de envío. Vacío: gladys@<su dominio>. |
| Asunto de las notificaciones | Asunto de los correos de notificación. Por defecto: Gladys. |
| Enviar también una versión HTML | Enlaces que se pueden pulsar e imagen de la cámara en el correo. Activado por defecto. |
| Límite de envío (correos por hora) | Por encima, los correos se rechazan hasta que pase la hora. Por defecto: 60. |
| Registrar los webhooks en Mailgun automáticamente | Vea Eventos de Mailgun. Activado por defecto. |
| Clave de firma de los webhooks | Desde la página Webhooks de Mailgun. Muy recomendable si usa los eventos. |
Pulse Probar la conexión: la respuesta indica si el dominio es conocido y está activo. Después Enviar un correo de prueba a su propia dirección.
Mi cuenta (cada usuario)
Cada usuario de Gladys indica su propia dirección de correo en el bloque Mi cuenta de la misma pantalla. Gladys envía las notificaciones de ese usuario a esa dirección. Un usuario sin dirección no recibe correos.
Notificaciones
Una vez indicada su dirección, cada notificación que Gladys le envía (alarma, escenas «Enviar un mensaje», imagen de cámara…) llega también por correo. La imagen de la cámara se muestra dentro del correo cuando la versión HTML está activada.
Acción de escena: «Enviar un correo»
En una escena, añada la acción Integraciones → Mailgun → Enviar un correo:
| Campo | Descripción |
|---|---|
| Para | Una o varias direcciones, separadas por comas (20 como máximo). |
| Asunto | Asunto del correo. |
| Mensaje | Texto del correo. |
| Copia / Copia oculta | Copias opcionales. |
| Responder a | Dirección de respuesta opcional. |
| Etiquetas de Mailgun | Hasta 3, separadas por comas. Útiles para filtrar los disparadores de abajo. |
Las variables de escena ({{...}}) funcionan en todos los campos. La acción devuelve:
sent:truecuando Mailgun aceptó el correo;message_id: el identificador de Mailgun del correo;error: por qué no se envió el correo (vacío en otro caso).
La acción nunca detiene la escena: compruebe sent en una condición si las acciones siguientes
dependen de ello.
Eventos de Mailgun (disparadores de escena)
Mailgun puede decirle a Gladys qué pasa con los correos. Mailgun debe poder llegar a su Gladys desde Internet, así que esto pasa por Gladys Plus:
- En la pantalla de configuración de Mailgun, pegue su clave Open API de Gladys Plus en el bloque Webhooks de Gladys Plus.
- Deje activado Registrar los webhooks en Mailgun automáticamente (necesita la clave de API privada), o pulse Registrar los webhooks de Mailgun. La integración añade su URL junto a las que ya pueda tener; Mailgun acepta 3 URL por evento.
- En Mailgun, abra Sending → Webhooks, copie la HTTP webhook signing key y péguela en Clave de firma de los webhooks. Con ella, solo los eventos realmente firmados por Mailgun inician sus escenas.
Los disparadores, en Integraciones → Mailgun:
| Disparador | Clave | Cuándo |
|---|---|---|
| Se entrega un correo | email_delivered | El servidor del destinatario aceptó el correo. |
| Falla un correo | email_failed | Mailgun no pudo entregarlo (permanente o temporal). |
| Se abre un correo | email_opened | El destinatario lo abrió (seguimiento de aperturas activado). |
| Se pulsa un enlace | email_clicked | Se pulsó un enlace (seguimiento de clics activado). |
| Correo marcado como spam | email_complained | El destinatario lo marcó como spam. |
| Un destinatario se da de baja | email_unsubscribed | El destinatario usó el enlace de baja. |
Cada disparador se puede filtrar por destinatario y por etiqueta (vacío = todos). «Falla un correo» también se puede filtrar por el tipo de fallo (permanente, temporal).
Variables disponibles en las acciones siguientes: {{triggerEvent.data.recipient}},
{{triggerEvent.data.subject}}, {{triggerEvent.data.tag}}, {{triggerEvent.data.message_id}},
más severity y reason para un fallo y url para un clic.
Evite una escena «cuando falla un correo, enviar un correo a la misma dirección»: puede entrar en bucle. El límite de envío la detiene, pero su cuota de Mailgun lo nota igualmente.
Widgets del panel
- Actividad de Mailgun: correos enviados, entregados, fallidos y abiertos en 24 horas, 7 o 30 días, un gráfico, el estado del dominio y de los eventos, cuántos correos envió Gladys en la última hora frente al límite, y los botones Correo de prueba y Actualizar. Las estadísticas necesitan la clave de API privada.
- Eventos de Mailgun: los últimos eventos recibidos (necesita Gladys Plus). Ajustes: cuántos mostrar, y todos los eventos o solo los problemas (fallos, spam, bajas).
Solución de problemas
| Mensaje | Qué hacer |
|---|---|
| «Mailgun rechazó la clave de API» | Compruebe la clave. Una clave de envío solo sirve para su dominio. |
| «Mailgun no conoce este dominio» | Compruebe cómo está escrito y la región (EE. UU./UE) de la cuenta. |
| «el dominio … está unverified» | Añada los registros DNS que indica Mailgun y verifíquelo. |
| «Límite de envío alcanzado» | Una escena envía demasiado. Corríjala o aumente el límite. |
| Los eventos nunca llegan | Compruebe Gladys Plus y pulse Registrar los webhooks de Mailgun. |
Eventos rechazados en los registros (signature) | La clave de firma no coincide con la de la página Webhooks de Mailgun. |
Los registros de la integración (Gladys → Integraciones → Mailgun → registros) dan más detalles.
Nunca muestran la clave de API y las direcciones se acortan (a***@ejemplo.es).
Privacidad
- La clave de API y la clave de firma se quedan en la configuración de Gladys.
- La integración guarda, en su propia carpeta
/data, los últimos 20 eventos recibidos (destinatario, asunto, fecha) para el widget, y la hora de los correos enviados en las últimas 24 horas para el límite de envío. Nada más.
Parámetros de configuración
Estos son los parámetros que Mailgun te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Primeros pasos | section | No | Necesita una cuenta de Mailgun y un dominio de envío. En Mailgun, cree una clave de envío (Domain settings, Sending keys) o use su clave de API privada, y compruebe la región de su cuenta (EE. UU. o UE). Después, cada usuario de Gladys indica su propia dirección de correo en el bloque «Mi cuenta» de abajo. |
| Clave de API de Mailgun | secret | Sí | Una clave de envío del dominio basta para enviar. Las estadísticas del widget y el registro automático de webhooks necesitan la clave de API privada. |
| Dominio de envío | string | Sí | El dominio tal como aparece en Mailgun, p. ej. mg.ejemplo.es (o su dominio sandbox). |
| Región de la cuenta | select | No | Dónde guarda Mailgun su cuenta. Un dominio creado en la región UE es desconocido para la API de EE. UU., y al revés. |
| Nombre del remitente | string | No | |
| Dirección del remitente | string | No | Una dirección del dominio de envío. Déjelo vacío para gladys@<su dominio>. |
| Asunto de las notificaciones | string | No | Asunto de los correos que Gladys envía como notificaciones (las escenas eligen el suyo). |
| Enviar también una versión HTML | boolean | No | Enlaces que se pueden pulsar y la imagen de la cámara en el correo. Desactivado: solo texto. |
| Límite de envío (correos por hora) | number | No | Protege su cuenta de Mailgun de una escena en bucle: por encima de este número, los correos se rechazan hasta que pase la hora. |
| Eventos de Mailgun (opcional) | section | No | Para iniciar escenas cuando un correo se entrega, falla, se abre o se pulsa, Mailgun debe poder llegar a Gladys: eso pasa por Gladys Plus. Pegue su clave Open API de Gladys Plus en el bloque «Webhooks de Gladys Plus» y la integración registra su URL en Mailgun por sí sola. Después copie abajo la «HTTP webhook signing key» de Mailgun (página Webhooks), para que solo Mailgun pueda iniciar sus escenas. |
| Registrar los webhooks en Mailgun automáticamente | boolean | No | Añade la URL de Gladys Plus a los webhooks de Mailgun del dominio, junto a las URL ya presentes (necesita la clave de API privada). |
| Clave de firma de los webhooks | secret | No | Desde la página Webhooks de Mailgun. Con ella, los eventos no firmados por Mailgun se rechazan. Muy recomendable. |
Cómo instalar Mailgun en Gladys
- En Gladys, abre Integraciones: Mailgun aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/prohand/gladys-mailgun:0.0.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/prohand/gladys-mailgun.
Mailgun requiere Gladys >=5.3.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
Mailgun es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene prohand, no el equipo principal de Gladys.
- Explorar todas las integraciones, nativas y de la comunidad
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación