Mailgun smart home integration, free and open source

Send Gladys notifications by email with Mailgun, and react to delivery events.
Send your Gladys notifications by email through Mailgun, send emails from your scenes, and start scenes when an email is delivered, fails, is opened or clicked.
Mailgun is a cloud service: Gladys needs Internet access to send emails.
What you need
- A Mailgun account (the free plan is enough to start).
- A sending domain in Mailgun, e.g.
mg.example.com. The sandbox domain Mailgun creates for you works too, but it only sends to the "authorized recipients" of your account. - An API key:
- a domain sending key (Mailgun → Sending → Domain settings → Sending keys) is enough to send emails;
- the private API key (Mailgun → API keys) is needed for the statistics of the widget and to register the webhooks automatically.
- The region of your account: US (
api.mailgun.net) or EU (api.eu.mailgun.net). A domain created in the EU region does not exist for the US API. - Optional: Gladys Plus, to receive the Mailgun events (delivered, failed, opened…) and start scenes with them.
Configuration
In Gladys: Integrations → Mailgun → Configuration.
| Field | What to fill in |
|---|---|
| Mailgun API key | The sending key or the private API key. |
| Sending domain | The domain as listed in Mailgun, e.g. mg.example.com. |
| Account region | United States or Europe. |
| Sender name | The name shown in the inbox. Default: Gladys. |
| Sender address | An address of the sending domain. Empty: gladys@<your domain>. |
| Subject of notifications | Subject of the notification emails. Default: Gladys. |
| Also send an HTML version | Clickable links and the camera image in the email. On by default. |
| Sending cap (emails per hour) | Past this number, emails are refused until the hour has passed. Default: 60. |
| Register the webhooks in Mailgun automatically | See Mailgun events. On by default. |
| HTTP webhook signing key | From the Mailgun Webhooks page. Strongly advised when you use the events. |
Click Test the connection: the answer tells whether the domain is known and active. Then Send a test email to your own address.
My account (each user)
Each Gladys user enters their own email address in the My account block of the same screen. Gladys sends that user's notifications to that address. A user without an address receives no email.
Notifications
Once your address is filled in, every notification Gladys sends you (alarm, scenes "Send a message", camera image…) also arrives by email. The camera image is shown inside the email when the HTML version is on.
Scene action: "Send an email"
In a scene, add the action Integrations → Mailgun → Send an email:
| Field | Description |
|---|---|
| To | One or more addresses, separated by commas (20 at most). |
| Subject | Subject of the email. |
| Message | Text of the email. |
| Cc / Bcc | Optional copies. |
| Reply to | Optional reply address. |
| Mailgun tags | Up to 3, separated by commas. Useful to filter the triggers below. |
Scene variables ({{...}}) work in every field. The action returns:
sent:truewhen Mailgun accepted the email;message_id: the Mailgun id of the email;error: why the email was not sent (empty otherwise).
The action never stops the scene: check sent in a condition if the next actions depend on it.
Mailgun events (scene triggers)
Mailgun can tell Gladys what happens to the emails. Mailgun must reach your Gladys from the Internet, so this goes through Gladys Plus:
- In the Mailgun configuration screen, paste your Gladys Plus Open API key in the Gladys Plus webhooks block.
- Keep Register the webhooks in Mailgun automatically on (needs the private API key), or click Register the Mailgun webhooks. The integration adds its URL next to the URLs you may already have; Mailgun accepts 3 URLs per event.
- In Mailgun, open Sending → Webhooks, copy the HTTP webhook signing key and paste it in HTTP webhook signing key. With it, only events really signed by Mailgun start your scenes.
The triggers, in Integrations → Mailgun:
| Trigger | Key | When |
|---|---|---|
| An email is delivered | email_delivered | The recipient's server accepted the email. |
| An email fails | email_failed | Mailgun could not deliver it (permanent or temporary). |
| An email is opened | email_opened | The recipient opened it (open tracking must be on). |
| A link is clicked | email_clicked | A link was clicked (click tracking must be on). |
| An email is reported as spam | email_complained | The recipient marked it as spam. |
| A recipient unsubscribes | email_unsubscribed | The recipient used the unsubscribe link. |
Each trigger can be filtered on the recipient and the tag (empty = any). "An email fails" can also be filtered on the kind of failure (permanent, temporary).
Variables available in the next actions: {{triggerEvent.data.recipient}},
{{triggerEvent.data.subject}}, {{triggerEvent.data.tag}}, {{triggerEvent.data.message_id}},
plus severity and reason for a failure and url for a click.
Avoid a scene "when an email fails, send an email to the same address": it can loop. The sending cap stops it, but your Mailgun quota still suffers.
Dashboard widgets
- Mailgun activity: emails sent, delivered, failed and opened over 24 hours, 7 or 30 days, a chart, the domain state, the state of the events, how many emails Gladys sent in the last hour against the cap, and the buttons Send a test email and Refresh. The statistics need the private API key.
- Mailgun events: the last events received (needs Gladys Plus). Setting: how many to show, and all events or problems only (failures, spam reports, unsubscriptions).
Troubleshooting
| Message | What to do |
|---|---|
| "Mailgun refused the API key" | Check the key. A sending key only works for its own domain. |
| "Mailgun does not know this domain" | Check the spelling, and the region (US/EU) of the account. |
| "domain … is unverified" | Add the DNS records Mailgun shows for the domain, then verify it. |
| "Sending cap reached" | A scene sends too much. Fix it, or raise the cap. |
| The events never arrive | Check Gladys Plus, then click Register the Mailgun webhooks. |
Events refused in the logs (signature) | The signing key does not match the one of the Mailgun Webhooks page. |
The integration logs (Gladys → Integrations → Mailgun → logs) give more details. They never show
the API key, and addresses are shortened (a***@example.com).
Privacy
- The API key and the signing key stay in the Gladys configuration.
- The integration keeps, in its own
/datafolder, the last 20 events received (recipient, subject, date) for the widget, and the time of the emails sent in the last 24 hours for the sending cap. Nothing else.
Configuration settings
These are the settings Mailgun asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Getting started | section | No | You need a Mailgun account and a sending domain. In Mailgun, create a sending API key (Domain settings, Sending keys) or use your private API key, and check the region of your account (US or EU). Then each Gladys user enters their own email address in the "My account" block below. |
| Mailgun API key | secret | Yes | A domain sending key is enough to send. The statistics of the widget and the automatic webhook setup need the private API key. |
| Sending domain | string | Yes | The domain as listed in Mailgun, e.g. mg.example.com (or your sandbox domain). |
| Account region | select | No | Where Mailgun stores your account. A domain created in the EU region is unknown to the US API, and the other way round. |
| Sender name | string | No | |
| Sender address | string | No | An address of the sending domain. Leave empty for gladys@<your domain>. |
| Subject of notifications | string | No | Subject of the emails Gladys sends as notifications (scenes choose their own). |
| Also send an HTML version | boolean | No | Clickable links and the camera image shown in the email. Off: plain text only. |
| Sending cap (emails per hour) | number | No | Protects your Mailgun account from a scene that loops: past this number, emails are refused until the hour has passed. |
| Mailgun events (optional) | section | No | To start scenes when an email is delivered, fails, is opened or clicked, Mailgun must reach Gladys: that goes through Gladys Plus. Paste your Gladys Plus Open API key in the "Gladys Plus webhooks" block, and the integration registers its URL in Mailgun by itself. Then copy the "HTTP webhook signing key" from Mailgun (Webhooks page) below, so that only Mailgun can start your scenes. |
| Register the webhooks in Mailgun automatically | boolean | No | Adds the Gladys Plus URL to the Mailgun webhooks of the domain, next to the URLs already there (needs the private API key). |
| HTTP webhook signing key | secret | No | From the Webhooks page of Mailgun. With it, events not signed by Mailgun are refused. Strongly advised. |
How to install Mailgun in Gladys
- In Gladys, open Integrations: Mailgun appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/prohand/gladys-mailgun:0.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/prohand/gladys-mailgun.
Mailgun requires Gladys >=5.3.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Mailgun is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by prohand, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation