Skip to content

Email

Shoutrrr can send notifications as email over SMTP. It talks to any RFC 5321 server (Gmail, Microsoft 365, self-hosted Postfix, and similar) using a single service URL.

URL Format

smtp://username:password@host:port/?fromaddress=fromAddress&toaddresses=recipient1[,recipient2,...]&subject=subject&auth=auth&encryption=encryption&useStartTLS=yes/no&useHTML=yes/no&clientHost=hostname&requirestarttls=yes/no&skiptlsverify=yes/no&timeout=duration&clientid=clientID&clientsecret=clientSecret&refreshtoken=refreshToken&tokenurl=tokenURL

URL Fields

  • Username - SMTP server username Default: empty
    URL part: smtp://username:password@host:port/
  • Password - SMTP server password, or the OAuth2 access token Default: empty
    URL part: smtp://username:password@host:port/
  • Host - SMTP server hostname or IP address (Required)
    URL part: smtp://username:password@host:port/
  • Port - SMTP server port, common ones are 25, 465, 587 or 2525 Default: 25
    URL part: smtp://username:password@host:port/

Query/Param Props

Props can be either supplied using the params argument or through the URL using ?key=value&key=value etc.

  • fromaddress - E-mail address that the mail are sent from (Required) Aliases: from

  • toaddresses - List of recipient e-mails (Required) Aliases: to

  • auth - SMTP authentication method Default: Unknown Possible values: None, Plain, CRAMMD5, Unknown, OAuth2, Login

  • clienthost - SMTP client hostname Default: localhost

  • clientid - OAuth2 client ID, for refreshing the access token Default: empty

  • clientsecret - OAuth2 client secret, for refreshing the access token Default: empty

  • encryption - Encryption method Default: Auto Possible values: None, ExplicitTLS, ImplicitTLS, Auto

  • fromname - Name of the sender Default: empty

  • refreshtoken - OAuth2 refresh token, for refreshing the access token Default: empty

  • requirestarttls - Fail if StartTLS is enabled but unsupported Default: ❌ No

  • skiptlsverify - Whether to skip TLS certificate verification Default: ❌ No

  • subject - The subject of the sent mail Default: empty Aliases: title

  • timeout - Timeout for the SMTP connection and session Default: 10s

  • tokenurl - OAuth2 token endpoint, for refreshing the access token Default: empty

  • usehtml - Whether the message being sent is in HTML Default: ❌ No

  • usestarttls - Whether to use StartTLS encryption Default: ✔ Yes Aliases: starttls

Getting Started

Every SMTP URL needs a host, a fromaddress, and at least one toaddresses recipient.

A Username and Password are required only when the server expects authentication.

Minimal authenticated send

smtp://user:[email protected]:587/[email protected]&[email protected]&requirestarttls=yes

Connects to mail.example.com on port 587, authenticates as user, and sends to [email protected].

Configuration Parameters

Host and Port

  • Host is the SMTP server hostname or IP address and is required.
  • Port defaults to 25.

Common ports:

  • 25: traditional SMTP (often blocked on residential networks)
  • 587: submission with STARTTLS
  • 465: implicit TLS (SMTPS)
  • 2525: alternate submission port used by some providers

Submission on 587

smtp://user:[email protected]:587/[email protected]&[email protected]&requirestarttls=yes

Username and Password

  • Username and Password are the SMTP credentials.
  • Both default to empty.
  • Leave them empty for servers that allow unauthenticated relay.
  • For auth=OAuth2, put the access token in the password field, or leave it empty and set the refresh settings.

No credentials

smtp://mail.example.com:25/[email protected]&[email protected]&auth=None

From Address and From Name

  • fromaddress (alias from) is the envelope and header From address and is required.
  • fromname is an optional display name shown by mail clients.

Named sender

smtp://user:[email protected]:587/[email protected]&fromname=Shoutrrr&[email protected]&requirestarttls=yes

Recipients

  • toaddresses (alias to) is a comma-separated list of recipient addresses and is required.
  • Plus-tags in addresses ([email protected]) are preserved and spaces that come from URL-decoding + are turned back into +.
  • Spaces around each address, such as after a comma, are ignored. To start an address with a literal +, write it as %2B.

Multiple recipients

smtp://user:[email protected]:587/[email protected]&[email protected],[email protected]&requirestarttls=yes

Plus-address recipient

smtp://user:[email protected]:587/[email protected]&[email protected]&requirestarttls=yes

Subject

  • subject (alias title) is the email subject.
  • When the URL omits subject, the header is empty.

Custom subject

smtp://user:[email protected]:587/[email protected]&[email protected]&subject=Disk%20space%20low&requirestarttls=yes

Authentication

auth selects the SMTP AUTH method. Default: Unknown.

Value Behavior
None No AUTH
Plain AUTH PLAIN (username and password)
Login AUTH LOGIN, for servers that do not support PLAIN
CRAMMD5 AUTH CRAM-MD5
OAuth2 SASL XOAUTH2 with the access token in the password field, or one from a refresh token
Unknown OAuth2 if a refresh token is set, Plain if a username is set, otherwise None

Plain, Login, and OAuth2 refuse to send credentials on an unencrypted connection unless the server name is localhost, 127.0.0.1, or ::1.

AUTH LOGIN

smtp://user:[email protected]:587/[email protected]&[email protected]&auth=Login&requirestarttls=yes

OAuth2 access token

smtp://user:[email protected]:587/[email protected]&[email protected]&auth=OAuth2&requirestarttls=yes

The access token is used as is. It expires after about an hour, so set the refresh settings for a URL that keeps working.

OAuth2 Token Refresh

With a refresh token, Shoutrrr gets a current access token from the provider's token endpoint before it connects to the SMTP server.

  • refreshtoken is the OAuth2 refresh token.
  • clientid is the OAuth2 client ID.
  • clientsecret is the OAuth2 client secret, which public clients leave empty.
  • tokenurl is the provider's token endpoint.
  • The token URL must use HTTPS, except for HTTP to localhost, 127.0.0.1, or ::1.
  • Setting a refresh token selects auth=OAuth2 by default.
  • Any other auth value with refresh settings is an error.
  • The password is ignored when a refresh token is set.
  • An access token is reused until it expires.
  • When the server rejects an access token, the next send gets a new one.
  • When the provider returns a new refresh token, later refreshes by the same service use it.
  • The URL keeps the original refresh token.

The OAuth2 generator writes these settings for you.

Provider Token URL Notes
Gmail https://oauth2.googleapis.com/token Use the scope https://mail.google.com/. A project whose consent screen is in testing gets refresh tokens that expire after 7 days.
Microsoft 365 https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token Add the offline_access scope next to https://outlook.office.com/SMTP.Send to get a refresh token. Refresh tokens expire after 90 days, so generate a new URL before then.

OAuth2 with a refresh token

smtp://alerts%[email protected]:587/[email protected]&[email protected]&auth=OAuth2&clientid=1234.apps.googleusercontent.com&clientsecret=secret&refreshtoken=1%2F%2F0abc&tokenurl=https%3A%2F%2Foauth2.googleapis.com%2Ftoken&requirestarttls=yes

Shoutrrr refreshes the access token as needed. When writing the URL by hand, percent-encode the values, as the example does.

Encryption

  • encryption selects how TLS is applied. Default: Auto.
  • usestarttls defaults to yes and is independent of encryption.
  • encryption=None still attempts STARTTLS unless you also set usestarttls=no.
Value Behavior
None No implicit TLS; STARTTLS is still attempted unless usestarttls=no
ExplicitTLS STARTTLS after connect when usestarttls is enabled; with usestarttls=no the session is plaintext
ImplicitTLS TLS from the first byte (typical for port 465)
Auto Implicit TLS on port 465; otherwise STARTTLS when usestarttls is enabled

Implicit TLS on 465

smtp://user:[email protected]:465/[email protected]&[email protected]&encryption=ImplicitTLS

StartTLS

  • usestarttls (alias starttls) defaults to yes.
  • When enabled and the server does not advertise STARTTLS, Shoutrrr logs a warning once and continues unencrypted unless requirestarttls is set.
  • Shoutrrr also logs a warning the first time a session sends without TLS, whatever the reason.

Disable STARTTLS

smtp://user:[email protected]:25/[email protected]&[email protected]&usestarttls=no

Require StartTLS

  • requirestarttls defaults to no.
  • When yes, send fails if STARTTLS is enabled but the server does not support it.

Fail closed without STARTTLS

smtp://user:[email protected]:587/[email protected]&[email protected]&requirestarttls=yes

Skip TLS Certificate Verification

  • skiptlsverify defaults to no.
  • When TLS is negotiated, yes disables server certificate verification. It does not enable TLS.
  • Shoutrrr logs a warning the first time a TLS session skips verification.

Security Risk

Skipping certificate verification makes the connection vulnerable to man-in-the-middle attacks. Only use this on networks you trust, such as a lab or an internal mail relay with a private CA.

Skip verify on an internal relay

smtp://user:[email protected]:587/[email protected]&[email protected]&skiptlsverify=yes&requirestarttls=yes

HTML Body

  • usehtml defaults to no.
  • When yes, the message is sent as multipart/alternative with a text/plain part and a text/html part.
  • The same message string is used for both parts.
  • The HTML part is sent as-is.

HTML notification

smtp://user:[email protected]:587/[email protected]&[email protected]&usehtml=yes&requirestarttls=yes

Pass HTML as the message body, for example <p>Disk usage is <strong>92%</strong>.</p>.

Client Host

  • clienthost is the hostname sent in the SMTP EHLO/HELO handshake.
  • Default: localhost.
  • Set it to auto to use the operating system hostname (falling back to localhost if lookup fails).

Auto client host

smtp://user:[email protected]:587/[email protected]&[email protected]&clienthost=auto&requirestarttls=yes

Timeout

  • timeout is a Go duration covering the TCP/TLS dial and the SMTP session (EHLO, AUTH, DATA, QUIT).
  • Default: 10s.
  • A caller's context deadline takes its place, whether it is earlier or later.
  • With no sender timeout set, the router waits this long for SMTP, including values above 10s. A positive SenderOptions.Timeout is the exact fixed timeout for every service on that sender.

Thirty-second timeout

smtp://user:[email protected]:587/[email protected]&[email protected]&timeout=30s&requirestarttls=yes

Message Templates

  • SMTP templates are only available via the Shoutrrr API.
  • They are not URL or CLI parameters.
  • IDs are "plain" and "HTML".
  • The template data map has a message key.

<div>-wrapped message body

err := service.SetTemplateString("HTML", `<div>{{ .message }}</div>`)

If you want a <pre> wrapper around an HTML part, include it in the message or set an "HTML" template

err := service.SetTemplateString("HTML", `<pre>{{ .message }}</pre>`)

Examples

STARTTLS on port 587

smtp://user:[email protected]:587/[email protected]&[email protected]&requirestarttls=yes

Implicit TLS on port 465

smtp://user:[email protected]:465/[email protected]&[email protected]&encryption=ImplicitTLS

HTML body

smtp://user:[email protected]:587/[email protected]&[email protected]&usehtml=yes&subject=Alert&requirestarttls=yes

Plus-address recipient

smtp://user:[email protected]:587/[email protected]&[email protected]&requirestarttls=yes

Unauthenticated local relay

smtp://127.0.0.1:25/[email protected]&[email protected]&auth=None&usestarttls=no