Saltar al contenido principal

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

Integración Mailgun para Gladys Assistant

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.

CampoQué indicar
Clave de API de MailgunLa clave de envío o la clave de API privada.
Dominio de envíoEl dominio tal como aparece en Mailgun, p. ej. mg.ejemplo.es.
Región de la cuentaEE. UU. o Europa.
Nombre del remitenteEl nombre que se ve en la bandeja de entrada. Por defecto: Gladys.
Dirección del remitenteUna dirección del dominio de envío. Vacío: gladys@<su dominio>.
Asunto de las notificacionesAsunto de los correos de notificación. Por defecto: Gladys.
Enviar también una versión HTMLEnlaces 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áticamenteVea Eventos de Mailgun. Activado por defecto.
Clave de firma de los webhooksDesde 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:

CampoDescripción
ParaUna o varias direcciones, separadas por comas (20 como máximo).
AsuntoAsunto del correo.
MensajeTexto del correo.
Copia / Copia ocultaCopias opcionales.
Responder aDirección de respuesta opcional.
Etiquetas de MailgunHasta 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: true cuando 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:

  1. En la pantalla de configuración de Mailgun, pegue su clave Open API de Gladys Plus en el bloque Webhooks de Gladys Plus.
  2. 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.
  3. 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:

DisparadorClaveCuándo
Se entrega un correoemail_deliveredEl servidor del destinatario aceptó el correo.
Falla un correoemail_failedMailgun no pudo entregarlo (permanente o temporal).
Se abre un correoemail_openedEl destinatario lo abrió (seguimiento de aperturas activado).
Se pulsa un enlaceemail_clickedSe pulsó un enlace (seguimiento de clics activado).
Correo marcado como spamemail_complainedEl destinatario lo marcó como spam.
Un destinatario se da de bajaemail_unsubscribedEl 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​

MensajeQué 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 lleganCompruebe 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ámetroTipoObligatorioDescripción
Primeros pasossectionNoNecesita 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 MailgunsecretSí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íostringSíEl dominio tal como aparece en Mailgun, p. ej. mg.ejemplo.es (o su dominio sandbox).
Región de la cuentaselectNoDó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 remitentestringNo
Dirección del remitentestringNoUna dirección del dominio de envío. Déjelo vacío para gladys@<su dominio>.
Asunto de las notificacionesstringNoAsunto de los correos que Gladys envía como notificaciones (las escenas eligen el suyo).
Enviar también una versión HTMLbooleanNoEnlaces 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)numberNoProtege 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)sectionNoPara 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áticamentebooleanNoAñ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 webhookssecretNoDesde la página Webhooks de Mailgun. Con ella, los eventos no firmados por Mailgun se rechazan. Muy recomendable.

Cómo instalar Mailgun en Gladys​

  1. En Gladys, abre Integraciones: Mailgun aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
  2. 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).
  3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
  4. 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.

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂