Zum Hauptinhalt springen

Mailgun Smart-Home-Integration, kostenlos und Open Source

Mailgun-Integration für Gladys Assistant

Sende Gladys-Benachrichtigungen per E-Mail mit Mailgun und reagiere auf Zustellungen.

Erhalte deine Gladys-Benachrichtigungen per E-Mail über Mailgun, sende E-Mails aus deinen Szenen und starte Szenen, wenn eine E-Mail zugestellt wird, fehlschlägt, geöffnet oder geklickt wird.

Mailgun ist ein Cloud-Dienst: Gladys braucht einen Internetzugang, um E-Mails zu senden.

Was du brauchst​

  • Ein Mailgun-Konto (der kostenlose Tarif reicht für den Anfang).
  • Eine Versanddomain in Mailgun, z. B. mg.beispiel.de. Die Sandbox-Domain, die Mailgun für dich anlegt, funktioniert auch, sendet aber nur an die „autorisierten Empfänger“ deines Kontos.
  • Einen API-Schlüssel:
    • ein Sendeschlüssel der Domain (Mailgun → Sending → Domain settings → Sending keys) reicht zum Senden von E-Mails;
    • der private API-Schlüssel (Mailgun → API keys) wird für die Statistiken des Widgets und für die automatische Webhook-Einrichtung gebraucht.
  • Die Region deines Kontos: US (api.mailgun.net) oder EU (api.eu.mailgun.net). Eine in der EU-Region angelegte Domain existiert für die US-API nicht.
  • Optional: Gladys Plus, um die Mailgun-Ereignisse (zugestellt, fehlgeschlagen, geöffnet…) zu empfangen und damit Szenen zu starten.

Konfiguration​

In Gladys: Integrationen → Mailgun → Konfiguration.

FeldWas einzutragen ist
Mailgun-API-SchlüsselDer Sendeschlüssel oder der private API-Schlüssel.
VersanddomainDie Domain, wie sie in Mailgun steht, z. B. mg.beispiel.de.
Region des KontosUSA oder Europa.
AbsendernameDer im Posteingang angezeigte Name. Standard: Gladys.
AbsenderadresseEine Adresse der Versanddomain. Leer: gladys@<deine Domain>.
Betreff der BenachrichtigungenBetreff der Benachrichtigungs-E-Mails. Standard: Gladys.
Auch eine HTML-Version sendenKlickbare Links und das Kamerabild in der E-Mail. Standardmäßig an.
Versandlimit (E-Mails pro Stunde)Darüber werden E-Mails abgelehnt, bis die Stunde vorbei ist. Standard: 60.
Webhooks automatisch in Mailgun eintragenSiehe Mailgun-Ereignisse. Standardmäßig an.
Webhook-SignaturschlüsselVon der Webhooks-Seite in Mailgun. Dringend empfohlen, wenn du die Ereignisse nutzt.

Klicke auf Verbindung testen: Die Antwort sagt, ob die Domain bekannt und aktiv ist. Dann Test-E-Mail senden an deine eigene Adresse.

Mein Konto (jeder Benutzer)​

Jeder Gladys-Benutzer gibt seine eigene E-Mail-Adresse im Block Mein Konto desselben Bildschirms ein. Gladys sendet die Benachrichtigungen dieses Benutzers an diese Adresse. Ein Benutzer ohne Adresse erhält keine E-Mail.

Benachrichtigungen​

Sobald deine Adresse eingetragen ist, kommt jede Benachrichtigung, die Gladys dir schickt (Alarm, Szenen „Nachricht senden“, Kamerabild…), auch per E-Mail an. Das Kamerabild wird in der E-Mail angezeigt, wenn die HTML-Version eingeschaltet ist.

Szenenaktion: „E-Mail senden“​

Füge in einer Szene die Aktion Integrationen → Mailgun → E-Mail senden hinzu:

FeldBeschreibung
AnEine oder mehrere Adressen, durch Kommas getrennt (höchstens 20).
BetreffBetreff der E-Mail.
NachrichtText der E-Mail.
Kopie / BlindkopieOptionale Kopien.
Antwort anOptionale Antwortadresse.
Mailgun-TagsBis zu 3, durch Kommas getrennt. Nützlich, um die Auslöser unten zu filtern.

Szenenvariablen ({{...}}) funktionieren in jedem Feld. Die Aktion liefert:

  • sent: true, wenn Mailgun die E-Mail angenommen hat;
  • message_id: die Mailgun-ID der E-Mail;
  • error: warum die E-Mail nicht gesendet wurde (sonst leer).

Die Aktion hält die Szene nie an: Prüfe sent in einer Bedingung, wenn die nächsten Aktionen davon abhängen.

Mailgun-Ereignisse (Szenenauslöser)​

Mailgun kann Gladys mitteilen, was mit den E-Mails passiert. Mailgun muss dein Gladys aus dem Internet erreichen, deshalb läuft das über Gladys Plus:

  1. Füge im Mailgun-Konfigurationsbildschirm deinen Gladys-Plus-Open-API-Schlüssel im Block Gladys-Plus-Webhooks ein.
  2. Lass Webhooks automatisch in Mailgun eintragen an (braucht den privaten API-Schlüssel) oder klicke auf Mailgun-Webhooks eintragen. Die Integration fügt ihre URL neben den URLs hinzu, die du vielleicht schon hast; Mailgun akzeptiert 3 URLs pro Ereignis.
  3. Öffne in Mailgun Sending → Webhooks, kopiere den HTTP webhook signing key und füge ihn in Webhook-Signaturschlüssel ein. Damit starten nur wirklich von Mailgun signierte Ereignisse deine Szenen.

Die Auslöser, unter Integrationen → Mailgun:

AuslöserSchlüsselWann
Eine E-Mail wird zugestelltemail_deliveredDer Server des Empfängers hat die E-Mail angenommen.
Eine E-Mail schlägt fehlemail_failedMailgun konnte sie nicht zustellen (dauerhaft oder vorübergehend).
Eine E-Mail wird geöffnetemail_openedDer Empfänger hat sie geöffnet (Öffnungs-Tracking an).
Ein Link wird geklicktemail_clickedEin Link wurde geklickt (Klick-Tracking an).
E-Mail als Spam gemeldetemail_complainedDer Empfänger hat sie als Spam markiert.
Ein Empfänger meldet sich abemail_unsubscribedDer Empfänger hat den Abmeldelink benutzt.

Jeder Auslöser lässt sich nach Empfänger und Tag filtern (leer = alle). „Eine E-Mail schlägt fehl“ lässt sich zusätzlich nach der Art des Fehlers filtern (dauerhaft, vorübergehend).

Variablen für die nächsten Aktionen: {{triggerEvent.data.recipient}}, {{triggerEvent.data.subject}}, {{triggerEvent.data.tag}}, {{triggerEvent.data.message_id}}, dazu severity und reason bei einem Fehler und url bei einem Klick.

Vermeide eine Szene „wenn eine E-Mail fehlschlägt, eine E-Mail an dieselbe Adresse senden“: Sie kann in eine Schleife geraten. Das Versandlimit stoppt sie, aber dein Mailgun-Kontingent leidet trotzdem.

Dashboard-Widgets​

  • Mailgun-Aktivität: gesendete, zugestellte, fehlgeschlagene und geöffnete E-Mails über 24 Stunden, 7 oder 30 Tage, ein Diagramm, der Zustand der Domain und der Ereignisse, wie viele E-Mails Gladys in der letzten Stunde im Vergleich zum Limit gesendet hat, und die Schaltflächen Test-E-Mail senden und Aktualisieren. Die Statistiken brauchen den privaten API-Schlüssel.
  • Mailgun-Ereignisse: die zuletzt empfangenen Ereignisse (braucht Gladys Plus). Einstellungen: wie viele angezeigt werden, und alle Ereignisse oder nur Probleme (Fehler, Spam-Meldungen, Abmeldungen).

Fehlerbehebung​

MeldungWas tun
„Mailgun hat den API-Schlüssel abgelehnt“Prüfe den Schlüssel. Ein Sendeschlüssel gilt nur für seine Domain.
„Mailgun kennt diese Domain nicht“Prüfe die Schreibweise und die Region (US/EU) des Kontos.
„Domain … ist unverified“Trage die DNS-Einträge ein, die Mailgun anzeigt, und verifiziere sie.
„Versandlimit erreicht“Eine Szene sendet zu viel. Korrigiere sie oder erhöhe das Limit.
Die Ereignisse kommen nie anPrüfe Gladys Plus und klicke dann auf Mailgun-Webhooks eintragen.
Abgelehnte Ereignisse in den Logs (signature)Der Signaturschlüssel passt nicht zu dem der Webhooks-Seite in Mailgun.

Die Logs der Integration (Gladys → Integrationen → Mailgun → Logs) geben mehr Details. Sie zeigen nie den API-Schlüssel, und Adressen werden gekürzt (a***@beispiel.de).

Datenschutz​

  • Der API-Schlüssel und der Signaturschlüssel bleiben in der Gladys-Konfiguration.
  • Die Integration speichert in ihrem eigenen Ordner /data die letzten 20 empfangenen Ereignisse (Empfänger, Betreff, Datum) für das Widget und die Uhrzeit der in den letzten 24 Stunden gesendeten E-Mails für das Versandlimit. Sonst nichts.

Konfigurationseinstellungen​

Diese Einstellungen fragt Mailgun in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
Erste SchrittesectionNeinDu brauchst ein Mailgun-Konto und eine Versanddomain. Erstelle in Mailgun einen Sendeschlüssel (Domain settings, Sending keys) oder nutze deinen privaten API-Schlüssel und prüfe die Region deines Kontos (US oder EU). Danach gibt jeder Gladys-Benutzer seine eigene E-Mail-Adresse im Block „Mein Konto“ unten ein.
Mailgun-API-SchlüsselsecretJaEin Sendeschlüssel der Domain reicht zum Senden. Die Statistiken des Widgets und die automatische Webhook-Einrichtung brauchen den privaten API-Schlüssel.
VersanddomainstringJaDie Domain, wie sie in Mailgun steht, z. B. mg.beispiel.de (oder deine Sandbox-Domain).
Region des KontosselectNeinWo Mailgun dein Konto speichert. Eine in der EU-Region erstellte Domain ist der US-API unbekannt und umgekehrt.
AbsendernamestringNein
AbsenderadressestringNeinEine Adresse der Versanddomain. Leer lassen für gladys@<deine Domain>.
Betreff der BenachrichtigungenstringNeinBetreff der E-Mails, die Gladys als Benachrichtigungen sendet (Szenen wählen ihren eigenen).
Auch eine HTML-Version sendenbooleanNeinKlickbare Links und das Kamerabild in der E-Mail. Aus: nur reiner Text.
Versandlimit (E-Mails pro Stunde)numberNeinSchützt dein Mailgun-Konto vor einer Szene in einer Schleife: Über dieser Zahl werden E-Mails abgelehnt, bis die Stunde vorbei ist.
Mailgun-Ereignisse (optional)sectionNeinUm Szenen zu starten, wenn eine E-Mail zugestellt wird, fehlschlägt, geöffnet oder geklickt wird, muss Mailgun Gladys erreichen: Das läuft über Gladys Plus. Füge deinen Gladys-Plus-Open-API-Schlüssel im Block „Gladys-Plus-Webhooks“ ein, und die Integration trägt ihre URL selbst in Mailgun ein. Kopiere dann den „HTTP webhook signing key“ aus Mailgun (Seite Webhooks) unten hinein, damit nur Mailgun deine Szenen starten kann.
Webhooks automatisch in Mailgun eintragenbooleanNeinFügt die Gladys-Plus-URL zu den Mailgun-Webhooks der Domain hinzu, neben die bereits vorhandenen URLs (braucht den privaten API-Schlüssel).
Webhook-SignaturschlüsselsecretNeinVon der Webhooks-Seite in Mailgun. Damit werden nicht von Mailgun signierte Ereignisse abgelehnt. Dringend empfohlen.

So installierst du Mailgun in Gladys​

  1. Öffne in Gladys Integrationen: Mailgun erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
  2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/prohand/gladys-mailgun:0.0.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
  3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
  4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/prohand/gladys-mailgun.

Mailgun benötigt Gladys >=5.3.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen​

Mailgun ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von prohand veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂