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

URL Fields

  • Username - SMTP server username Default: empty
    URL part: smtp://username:password@host:port/
  • Password - SMTP server password or hash (for OAuth2) 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

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

  • fromname - Name of the sender 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

  • 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.

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 +.

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 a static access token in the password field (no refresh)
Unknown If a username is set, treated as Plain; 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 token is not refreshed. Supply a current access token for each send.

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 and continues unencrypted unless requirestarttls is set.

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; however, it does not enable TLS.

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.

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