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=FROM_ADDRESS&toaddresses=TO_ADDRESS_1[,TO_ADDRESS_2,...][&subject=SUBJECT][&auth=AUTH][&encryption=ENCRYPTION][&useStartTLS={yes|no}][&useHTML={yes|no}][&clientHost=CLIENT_HOST][&requirestarttls={yes|no}][&skiptlsverify={yes|no}][&timeout=DURATION][&clientid=CLIENT_ID][&clientsecret=CLIENT_SECRET][&refreshtoken=REFRESH_TOKEN][&scopes=SCOPES][&tokenurl=TOKEN_URL]

URL Fields

  • Username - SMTP server username Default: empty
    URL part: User
  • Password - SMTP server password, or the OAuth2 access token Default: empty
    URL part: Password
  • Host - SMTP server hostname or IP address (Required)
    URL part: Host
  • Port - SMTP server port, common ones are 25, 465, 587 or 2525 Default: 25
    URL part: 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: Unknown, None, Plain, CRAMMD5, OAuth2, Login

  • clienthost - SMTP client hostname Default: localhost

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

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

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

  • 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

  • scopes - OAuth2 scopes, for the client credentials grant Default: empty

  • 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 getting 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://USERNAME:[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://USERNAME:[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 or the client credentials 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://USERNAME:[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://USERNAME:[email protected]:587/[email protected]&[email protected],[email protected]&requirestarttls=yes

Plus-address recipient

smtp://USERNAME:[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://USERNAME:[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 the token endpoint
Unknown OAuth2 if a refresh token or scopes are 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.

Microsoft 365 is retiring Plain and Login for SMTP AUTH. The Microsoft 365 guide covers the OAuth2 alternatives.

AUTH LOGIN

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

OAuth2 access token

smtp://USERNAME:[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 or the client credentials 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_ID/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=CLIENT_ID&clientsecret=CLIENT_SECRET&refreshtoken=REFRESH_TOKEN&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 for the token URL.

OAuth2 Client Credentials

With the client credentials grant, an application gets its access token with its own client ID and secret, without a user's sign-in or a refresh token. Shoutrrr requests a current access token from the provider's token endpoint before it connects to the SMTP server.

  • clientid is the OAuth2 client ID.
  • clientsecret is the OAuth2 client secret, which this grant requires.
  • scopes lists the scopes to request, separated by commas.
  • tokenurl is the provider's token endpoint.
  • The username is the mailbox the application sends as.
  • The token URL must use HTTPS, except for HTTP to localhost, 127.0.0.1, or ::1.
  • Setting scopes selects auth=OAuth2 by default.
  • Scopes with a refresh token are an error, since a refresh request sends no scopes.
  • The password is ignored when scopes are set.
  • An access token is reused until it expires.
  • When the server rejects an access token, the next send gets a new one.

The Microsoft 365 guide shows how to set up client credentials for Exchange Online.

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://USERNAME:[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.

Configs built in Go

A smtp.Config built in Go gets the URL defaults for the fields it leaves unset, except STARTTLS. An unset Auth is Unknown, which picks the method from the credentials, and an unset Encryption is Auto. An unset UseStartTLS is false, so set it to true to use STARTTLS. Without TLS, the Plain and Login methods refuse to send credentials to a server other than localhost.

Disable STARTTLS

smtp://USERNAME:[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://USERNAME:[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://USERNAME:[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://USERNAME:[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://USERNAME:[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://USERNAME:[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://USERNAME:[email protected]:587/[email protected]&[email protected]&requirestarttls=yes

Implicit TLS on port 465

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

HTML body

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

Plus-address recipient

smtp://USERNAME:[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