Skip to main content

SMTP integration for Gladys Assistant

SMTP integration for Gladys Assistant

Send emails from Gladys through your own SMTP server.

View on GitHubAll external integrations

This integration lets Gladys send emails through your own SMTP server — your mailbox provider (Gmail, Outlook, iCloud, Fastmail…), a transactional service (Brevo, Mailgun, Postmark, Amazon SES…), or a mail server running on your local network.

Once installed, "email" becomes a notification channel: your scenes can send you a message, and Gladys can reach you when you are away from the app.

How it works​

There are two levels of settings, and they are not the same thing:

  • The SMTP server (the Configuration block) — shared by the whole house, set once by the administrator. This is the account Gladys uses to send.
  • Your email address (the My account block) — each user of the Gladys instance enters their own address, and receives their own notifications there. A user who leaves it empty is simply skipped: Gladys never sends them an email.

Configuring the SMTP server​

  1. Open the Configuration tab of the integration.
  2. Fill in the settings of your provider:
    • SMTP server: the hostname, e.g. smtp.gmail.com.
    • Port and Encryption: 587 with STARTTLS for most providers, 465 with TLS / SSL for the others. Use 25 with None only for a relay on your own network.
    • Username and Password: the credentials of the sending account. Leave both empty for a local relay that accepts anonymous submissions.
    • Sender address: the address the emails come from. Most providers require it to be the authenticated account itself, otherwise they reject the message.
    • Sender name: what the recipient sees in their mailbox.
    • Subject prefix: prepended to every subject, which is built from the first line of the message — leave it empty if you prefer no prefix.
  3. Save, then click Test the SMTP connection. It opens a session and authenticates without sending anything: if it fails, the message under the button tells you what the server refused.
  4. Click Send a test email and check that the email actually arrives — including the spam folder, which no connection test can do for you.

Settings of the common providers​

ProviderServerPortEncryption
Gmailsmtp.gmail.com587STARTTLS
Outlook / Microsoftsmtp-mail.outlook.com587STARTTLS
iCloudsmtp.mail.me.com587STARTTLS
Fastmailsmtp.fastmail.com465TLS / SSL
Brevosmtp-relay.brevo.com587STARTTLS
Mailgunsmtp.mailgun.org587STARTTLS
Amazon SESemail-smtp.<region>.amazonaws.com587STARTTLS

Gmail, Outlook and iCloud refuse your account password. They require an app password: enable two-factor authentication on the account, generate a dedicated password for Gladys, and paste that one in the Password field. Revoking it later disables Gladys only, not your account.

Receiving the notifications​

  1. Still in the Configuration tab, find the My account block.
  2. Enter your email address and save.
  3. Every Gladys user does the same, each with their own address.

What an email looks like​

The message Gladys sends becomes the body of the email. Its subject is built from the first line of the message (prefixed with your subject prefix), so a mailbox list stays readable without opening anything.

When the message carries an image — a camera snapshot, for instance — it is attached to the email and displayed inline in the body.

Troubleshooting​

  • "authentication refused by the server" — wrong username or password. On Gmail, Outlook and iCloud, this is almost always the account password used instead of an app password.
  • "cannot reach the server" — wrong hostname or port, or a firewall blocking outgoing SMTP. Some ISPs block port 25 for residential lines: use 587 or 465.
  • "the TLS handshake failed" — the encryption mode does not match the port. Port 465 needs TLS / SSL, port 587 needs STARTTLS.
  • "the server refused the sender or the recipient address" — the sender address is not the authenticated account, or the recipient address is invalid.
  • A local mail server with a self-signed certificate — turn off Verify the TLS certificate. Leave it on in every other case.
  • The emails go to spam — add the sender address to your contacts, or use a domain with SPF/DKIM records if you own one.

The integration logs everything it does: open the integration logs from the Gladys UI (or docker logs on the host), with LOG_LEVEL=debug for the full detail of the SMTP dialogue.

Configuration settings​

These are the settings SMTP asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your SMTP serversectionNoGladys sends its notifications as emails through the SMTP server you configure here. Any provider works: your mailbox provider, a transactional service, or a mail server on your LAN. Each user then enters their own email address in the "My account" block below.
SMTP serverstringYesHostname or IP address of the SMTP server, e.g. smtp.gmail.com.
PortnumberYes587 for STARTTLS (most common), 465 for implicit TLS, 25 for a local relay.
EncryptionselectYesHow the connection is secured. Pick STARTTLS on port 587, TLS on port 465.
UsernamestringNoSMTP account used to authenticate. Leave empty for a relay that accepts anonymous submissions.
PasswordsecretNoSMTP password. With Gmail, Outlook or iCloud, generate a dedicated app password instead of using your account password.
Sender addressstringYesAddress the emails are sent from. Most providers require it to match the authenticated account.
Sender namestringNoDisplay name shown in the recipient's mailbox.
Subject prefixstringNoPrepended to every subject, which is built from the first line of the message. Leave empty for no prefix.
Verify the TLS certificatebooleanNoKeep it on. Turn it off only for a local mail server using a self-signed certificate.

How to install SMTP in Gladys​

  1. In Gladys, open Integrations: SMTP appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/gladysassistant/gladys-smtp:1.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/GladysAssistant/gladys-smtp.

SMTP requires Gladys >=4.62.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​

SMTP 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 GladysAssistant, 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 🙂
Last updated on