Mailgun Smart-Home-Integration, kostenlos und Open Source

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.
| Feld | Was einzutragen ist |
|---|---|
| Mailgun-API-Schlüssel | Der Sendeschlüssel oder der private API-Schlüssel. |
| Versanddomain | Die Domain, wie sie in Mailgun steht, z. B. mg.beispiel.de. |
| Region des Kontos | USA oder Europa. |
| Absendername | Der im Posteingang angezeigte Name. Standard: Gladys. |
| Absenderadresse | Eine Adresse der Versanddomain. Leer: gladys@<deine Domain>. |
| Betreff der Benachrichtigungen | Betreff der Benachrichtigungs-E-Mails. Standard: Gladys. |
| Auch eine HTML-Version senden | Klickbare 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 eintragen | Siehe Mailgun-Ereignisse. Standardmäßig an. |
| Webhook-Signaturschlüssel | Von 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:
| Feld | Beschreibung |
|---|---|
| An | Eine oder mehrere Adressen, durch Kommas getrennt (höchstens 20). |
| Betreff | Betreff der E-Mail. |
| Nachricht | Text der E-Mail. |
| Kopie / Blindkopie | Optionale Kopien. |
| Antwort an | Optionale Antwortadresse. |
| Mailgun-Tags | Bis 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:
- Füge im Mailgun-Konfigurationsbildschirm deinen Gladys-Plus-Open-API-Schlüssel im Block Gladys-Plus-Webhooks ein.
- 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.
- Ö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öser | Schlüssel | Wann |
|---|---|---|
| Eine E-Mail wird zugestellt | email_delivered | Der Server des Empfängers hat die E-Mail angenommen. |
| Eine E-Mail schlägt fehl | email_failed | Mailgun konnte sie nicht zustellen (dauerhaft oder vorübergehend). |
| Eine E-Mail wird geöffnet | email_opened | Der Empfänger hat sie geöffnet (Öffnungs-Tracking an). |
| Ein Link wird geklickt | email_clicked | Ein Link wurde geklickt (Klick-Tracking an). |
| E-Mail als Spam gemeldet | email_complained | Der Empfänger hat sie als Spam markiert. |
| Ein Empfänger meldet sich ab | email_unsubscribed | Der 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
| Meldung | Was 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 an | Prü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
/datadie 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.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Erste Schritte | section | Nein | Du 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üssel | secret | Ja | Ein Sendeschlüssel der Domain reicht zum Senden. Die Statistiken des Widgets und die automatische Webhook-Einrichtung brauchen den privaten API-Schlüssel. |
| Versanddomain | string | Ja | Die Domain, wie sie in Mailgun steht, z. B. mg.beispiel.de (oder deine Sandbox-Domain). |
| Region des Kontos | select | Nein | Wo Mailgun dein Konto speichert. Eine in der EU-Region erstellte Domain ist der US-API unbekannt und umgekehrt. |
| Absendername | string | Nein | |
| Absenderadresse | string | Nein | Eine Adresse der Versanddomain. Leer lassen für gladys@<deine Domain>. |
| Betreff der Benachrichtigungen | string | Nein | Betreff der E-Mails, die Gladys als Benachrichtigungen sendet (Szenen wählen ihren eigenen). |
| Auch eine HTML-Version senden | boolean | Nein | Klickbare Links und das Kamerabild in der E-Mail. Aus: nur reiner Text. |
| Versandlimit (E-Mails pro Stunde) | number | Nein | Schü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) | section | Nein | Um 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 eintragen | boolean | Nein | Fü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üssel | secret | Nein | Von der Webhooks-Seite in Mailgun. Damit werden nicht von Mailgun signierte Ereignisse abgelehnt. Dringend empfohlen. |
So installierst du Mailgun in Gladys
- Öffne in Gladys Integrationen: Mailgun erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- 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). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- 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.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation