Skip to main content

Mailgun smart home integration, free and open source

Mailgun integration for Gladys Assistant

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.

FieldWhat to fill in
Mailgun API keyThe sending key or the private API key.
Sending domainThe domain as listed in Mailgun, e.g. mg.example.com.
Account regionUnited States or Europe.
Sender nameThe name shown in the inbox. Default: Gladys.
Sender addressAn address of the sending domain. Empty: gladys@<your domain>.
Subject of notificationsSubject of the notification emails. Default: Gladys.
Also send an HTML versionClickable 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 automaticallySee Mailgun events. On by default.
HTTP webhook signing keyFrom 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:

FieldDescription
ToOne or more addresses, separated by commas (20 at most).
SubjectSubject of the email.
MessageText of the email.
Cc / BccOptional copies.
Reply toOptional reply address.
Mailgun tagsUp to 3, separated by commas. Useful to filter the triggers below.

Scene variables ({{...}}) work in every field. The action returns:

  • sent: true when 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:

  1. In the Mailgun configuration screen, paste your Gladys Plus Open API key in the Gladys Plus webhooks block.
  2. 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.
  3. 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:

TriggerKeyWhen
An email is deliveredemail_deliveredThe recipient's server accepted the email.
An email failsemail_failedMailgun could not deliver it (permanent or temporary).
An email is openedemail_openedThe recipient opened it (open tracking must be on).
A link is clickedemail_clickedA link was clicked (click tracking must be on).
An email is reported as spamemail_complainedThe recipient marked it as spam.
A recipient unsubscribesemail_unsubscribedThe 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​

MessageWhat 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 arriveCheck 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 /data folder, 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.

SettingTypeRequiredDescription
Getting startedsectionNoYou 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 keysecretYesA domain sending key is enough to send. The statistics of the widget and the automatic webhook setup need the private API key.
Sending domainstringYesThe domain as listed in Mailgun, e.g. mg.example.com (or your sandbox domain).
Account regionselectNoWhere Mailgun stores your account. A domain created in the EU region is unknown to the US API, and the other way round.
Sender namestringNo
Sender addressstringNoAn address of the sending domain. Leave empty for gladys@<your domain>.
Subject of notificationsstringNoSubject of the emails Gladys sends as notifications (scenes choose their own).
Also send an HTML versionbooleanNoClickable links and the camera image shown in the email. Off: plain text only.
Sending cap (emails per hour)numberNoProtects your Mailgun account from a scene that loops: past this number, emails are refused until the hour has passed.
Mailgun events (optional)sectionNoTo 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 automaticallybooleanNoAdds 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 keysecretNoFrom the Webhooks page of Mailgun. With it, events not signed by Mailgun are refused. Strongly advised.

How to install Mailgun in Gladys​

  1. In Gladys, open Integrations: Mailgun appears in the catalog, next to the native integrations, with a community badge.
  2. 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).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. 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.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂