Aller au contenu principal

Intégration domotique Mailgun, gratuite et open source

Intégration Mailgun pour Gladys Assistant

Envoyez les notifications Gladys par e-mail avec Mailgun et réagissez aux livraisons.

Recevez vos notifications Gladys par e-mail via Mailgun, envoyez des e-mails depuis vos scènes, et lancez des scènes quand un e-mail est délivré, échoue, est ouvert ou cliqué.

Mailgun est un service cloud : Gladys a besoin d'un accès Internet pour envoyer les e-mails.

Ce qu'il vous faut​

  • Un compte Mailgun (l'offre gratuite suffit pour commencer).
  • Un domaine d'envoi dans Mailgun, par exemple mg.exemple.fr. Le domaine « sandbox » que Mailgun crée pour vous marche aussi, mais il n'envoie qu'aux « destinataires autorisés » de votre compte.
  • Une clé d'API :
    • une clé d'envoi du domaine (Mailgun → Sending → Domain settings → Sending keys) suffit pour envoyer des e-mails ;
    • la clé d'API privée (Mailgun → API keys) est nécessaire pour les statistiques du widget et pour inscrire les webhooks automatiquement.
  • La région de votre compte : US (api.mailgun.net) ou UE (api.eu.mailgun.net). Un domaine créé dans la région UE n'existe pas pour l'API US.
  • Facultatif : Gladys Plus, pour recevoir les événements Mailgun (délivré, échec, ouvert…) et lancer des scènes avec.

Configuration​

Dans Gladys : Intégrations → Mailgun → Configuration.

ChampÀ renseigner
Clé d'API MailgunLa clé d'envoi ou la clé d'API privée.
Domaine d'envoiLe domaine tel que listé dans Mailgun, par exemple mg.exemple.fr.
Région du compteÉtats-Unis ou Europe.
Nom de l'expéditeurLe nom affiché dans la boîte de réception. Par défaut : Gladys.
Adresse de l'expéditeurUne adresse du domaine d'envoi. Vide : gladys@<votre domaine>.
Objet des notificationsObjet des e-mails de notification. Par défaut : Gladys.
Envoyer aussi une version HTMLLiens cliquables et image de caméra dans l'e-mail. Activé par défaut.
Limite d'envoi (e-mails par heure)Au-delà, les e-mails sont refusés jusqu'à ce que l'heure soit passée. Défaut : 60.
Inscrire les webhooks dans Mailgun automatiquementVoir Événements Mailgun. Activé par défaut.
Clé de signature des webhooksDepuis la page Webhooks de Mailgun. Fortement conseillé si vous utilisez les événements.

Cliquez sur Tester la connexion : la réponse dit si le domaine est connu et actif. Puis Envoyer un e-mail de test à votre propre adresse.

Mon compte (chaque utilisateur)​

Chaque utilisateur Gladys saisit sa propre adresse e-mail dans le bloc Mon compte du même écran. Gladys envoie les notifications de cet utilisateur à cette adresse. Un utilisateur sans adresse ne reçoit pas d'e-mail.

Notifications​

Une fois votre adresse renseignée, chaque notification que Gladys vous envoie (alarme, scènes « Envoyer un message », image de caméra…) arrive aussi par e-mail. L'image de caméra est affichée dans l'e-mail quand la version HTML est activée.

Action de scène : « Envoyer un e-mail »​

Dans une scène, ajoutez l'action Intégrations → Mailgun → Envoyer un e-mail :

ChampDescription
DestinatairesUne ou plusieurs adresses, séparées par des virgules (20 au maximum).
ObjetObjet de l'e-mail.
MessageTexte de l'e-mail.
Copie / Copie cachéeCopies facultatives.
Répondre àAdresse de réponse facultative.
Étiquettes MailgunJusqu'à 3, séparées par des virgules. Utile pour filtrer les déclencheurs ci-dessous.

Les variables de scène ({{...}}) marchent dans tous les champs. L'action renvoie :

  • sent : true quand Mailgun a accepté l'e-mail ;
  • message_id : l'identifiant Mailgun de l'e-mail ;
  • error : pourquoi l'e-mail n'est pas parti (vide sinon).

L'action n'arrête jamais la scène : testez sent dans une condition si la suite en dépend.

Événements Mailgun (déclencheurs de scène)​

Mailgun peut dire à Gladys ce que deviennent les e-mails. Mailgun doit joindre votre Gladys depuis Internet : cela passe par Gladys Plus.

  1. Dans l'écran de configuration Mailgun, collez votre clé Open API Gladys Plus dans le bloc Webhooks Gladys Plus.
  2. Laissez Inscrire les webhooks dans Mailgun automatiquement activé (demande la clé d'API privée), ou cliquez sur Inscrire les webhooks Mailgun. L'intégration ajoute son URL à côté de celles que vous avez déjà ; Mailgun accepte 3 URL par événement.
  3. Dans Mailgun, ouvrez Sending → Webhooks, copiez la HTTP webhook signing key et collez-la dans Clé de signature des webhooks. Avec elle, seuls les événements vraiment signés par Mailgun lancent vos scènes.

Les déclencheurs, dans Intégrations → Mailgun :

DéclencheurCléQuand
Un e-mail est délivréemail_deliveredLe serveur du destinataire a accepté l'e-mail.
Un e-mail échoueemail_failedMailgun n'a pas pu le délivrer (permanent ou temporaire).
Un e-mail est ouvertemail_openedLe destinataire l'a ouvert (suivi des ouvertures activé).
Un lien est cliquéemail_clickedUn lien a été cliqué (suivi des clics activé).
Un e-mail est signalé spamemail_complainedLe destinataire l'a marqué comme spam.
Un destinataire se désabonneemail_unsubscribedLe destinataire a utilisé le lien de désabonnement.

Chaque déclencheur peut être filtré sur le destinataire et l'étiquette (vide = tous). « Un e-mail échoue » peut aussi être filtré sur le type d'échec (permanent, temporaire).

Variables disponibles dans les actions suivantes : {{triggerEvent.data.recipient}}, {{triggerEvent.data.subject}}, {{triggerEvent.data.tag}}, {{triggerEvent.data.message_id}}, plus severity et reason pour un échec et url pour un clic.

Évitez une scène « quand un e-mail échoue, envoyer un e-mail à la même adresse » : elle peut boucler. La limite d'envoi l'arrête, mais votre quota Mailgun en pâtit quand même.

Widgets du tableau de bord​

  • Activité Mailgun : e-mails envoyés, délivrés, en échec et ouverts sur 24 heures, 7 ou 30 jours, un graphique, l'état du domaine, l'état des événements, le nombre d'e-mails envoyés par Gladys dans la dernière heure face à la limite, et les boutons E-mail de test et Actualiser. Les statistiques demandent la clé d'API privée.
  • Événements Mailgun : les derniers événements reçus (demande Gladys Plus). Réglages : combien en afficher, et tous les événements ou les problèmes seulement (échecs, spam, désabonnements).

En cas de problème​

MessageQue faire
« Mailgun a refusé la clé d'API »Vérifiez la clé. Une clé d'envoi ne marche que pour son domaine.
« Mailgun ne connaît pas ce domaine »Vérifiez l'orthographe, et la région (US/UE) du compte.
« le domaine … est unverified »Ajoutez les enregistrements DNS que Mailgun indique, puis vérifiez-le.
« Limite d'envoi atteinte »Une scène envoie trop. Corrigez-la, ou augmentez la limite.
Les événements n'arrivent jamaisVérifiez Gladys Plus, puis cliquez sur Inscrire les webhooks Mailgun.
Événements refusés dans les logs (signature)La clé de signature ne correspond pas à celle de la page Webhooks de Mailgun.

Les logs de l'intégration (Gladys → Intégrations → Mailgun → logs) donnent plus de détails. Ils n'affichent jamais la clé d'API, et les adresses sont raccourcies (a***@exemple.fr).

Vie privée​

  • La clé d'API et la clé de signature restent dans la configuration de Gladys.
  • L'intégration garde, dans son propre dossier /data, les 20 derniers événements reçus (destinataire, objet, date) pour le widget, et l'heure des e-mails envoyés dans les dernières 24 heures pour la limite d'envoi. Rien d'autre.

Paramètres de configuration​

Voici les paramètres demandés par Mailgun dans son écran de configuration dans Gladys.

ParamètreTypeObligatoireDescription
Pour commencersectionNonIl vous faut un compte Mailgun et un domaine d'envoi. Dans Mailgun, créez une clé d'envoi (Domain settings, Sending keys) ou utilisez votre clé d'API privée, et vérifiez la région de votre compte (US ou UE). Ensuite, chaque utilisateur Gladys saisit sa propre adresse e-mail dans le bloc « Mon compte » ci-dessous.
Clé d'API MailgunsecretOuiUne clé d'envoi du domaine suffit pour envoyer. Les statistiques du widget et l'inscription automatique des webhooks demandent la clé d'API privée.
Domaine d'envoistringOuiLe domaine tel que listé dans Mailgun, par exemple mg.exemple.fr (ou votre domaine sandbox).
Région du compteselectNonOù Mailgun héberge votre compte. Un domaine créé dans la région UE est inconnu de l'API US, et inversement.
Nom de l'expéditeurstringNon
Adresse de l'expéditeurstringNonUne adresse du domaine d'envoi. Laissez vide pour gladys@<votre domaine>.
Objet des notificationsstringNonObjet des e-mails que Gladys envoie comme notifications (les scènes choisissent le leur).
Envoyer aussi une version HTMLbooleanNonLiens cliquables et image de caméra affichée dans l'e-mail. Désactivé : texte brut uniquement.
Limite d'envoi (e-mails par heure)numberNonProtège votre compte Mailgun d'une scène qui boucle : au-delà de ce nombre, les e-mails sont refusés jusqu'à ce que l'heure soit passée.
Événements Mailgun (facultatif)sectionNonPour lancer des scènes quand un e-mail est délivré, échoue, est ouvert ou cliqué, Mailgun doit pouvoir joindre Gladys : cela passe par Gladys Plus. Collez votre clé Open API Gladys Plus dans le bloc « Webhooks Gladys Plus », et l'intégration inscrit son URL dans Mailgun toute seule. Copiez ensuite ci-dessous la « HTTP webhook signing key » de Mailgun (page Webhooks), pour que seul Mailgun puisse lancer vos scènes.
Inscrire les webhooks dans Mailgun automatiquementbooleanNonAjoute l'URL Gladys Plus aux webhooks Mailgun du domaine, à côté des URL déjà présentes (demande la clé d'API privée).
Clé de signature des webhookssecretNonDepuis la page Webhooks de Mailgun. Avec elle, les événements non signés par Mailgun sont refusés. Fortement conseillé.

Comment installer Mailgun dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : Mailgun apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
  2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/prohand/gladys-mailgun:0.0.1), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration).
  3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
  4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/prohand/gladys-mailgun.

Mailgun nécessite Gladys >=5.3.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.

Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.

À propos des intégrations externes​

Mailgun est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par prohand, et non par l'équipe cœur de Gladys.

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂