Grafana SMTP Email Configuration: [smtp] Settings and TLS

Updated

grafana smtp configuration

This [smtp] block sends mail on Grafana 13.1.3. Put it in grafana.ini (/etc/grafana/grafana.ini on Debian/RPM), restart Grafana. Running your own mail path is one of the costs that come with self-hosting Grafana rather than buying it; on a hosted instance there is no grafana.ini to edit. Then trigger a real send with curl -X POST http://localhost:3000/api/user/password/send-reset-email -H 'Content-Type: application/json' -d '{"userOrEmail":"you@example.com"}'.

[smtp]
enabled = true
host = smtp.example.com:587
user = apikey
password = """your-password"""
startTLS_policy = MandatoryStartTLS
skip_verify = false
from_address = grafana@example.com
from_name = Grafana

Wrap the password in triple quotes if it contains # or ;. There is no port key — the port is part of host.

The full key set, and the one port that behaves differently

Every key Grafana 13.1.3 reads from [smtp], taken from its own conf/defaults.ini: enabled, host, user, password, cert_file, key_file, skip_verify, from_address, from_name, ehlo_identity, startTLS_policy, enable_tracing. A separate [smtp.static_headers] section adds headers to outgoing mail. Anything else you have seen in a blog post is not a Grafana setting.

Grafana’s documentation gives exactly one rule about ports: “Use port 465 for implicit TLS.” Take that literally — implicit TLS is switched on by the port number being 465 and nothing else. Ports 587 and 25 open in plaintext and then do whatever startTLS_policy says. I could not bind port 465 without root on this machine, so the “only 465” rule is cited rather than demonstrated; what is demonstrated below is what happens when you get it wrong.

startTLS_policy: four values, no validation

The accepted values are OpportunisticStartTLS, MandatoryStartTLS, NoStartTLS, and empty. Empty means opportunistic. So does any typo — an unrecognised value is not a startup error, it silently leaves you encrypting only if the server happens to offer it. If you care whether the connection is encrypted, set MandatoryStartTLS explicitly.

Whether STARTTLS is offered at all is the server’s decision, and one command tells you. Two mailpit listeners, same binary, one with a certificate configured:

$ printf 'EHLO probe.local\r\nQUIT\r\n' | nc -w 3 127.0.0.1 1025
250-SIZE 52428800
250-ENHANCEDSTATUSCODES
250-8BITMIME
250 SMTPUTF8

$ printf 'EHLO probe.local\r\nQUIT\r\n' | nc -w 3 127.0.0.1 1587
250-SIZE 52428800
250-STARTTLS
250-ENHANCEDSTATUSCODES
250-8BITMIME
250 SMTPUTF8

Point Grafana at the first with MandatoryStartTLS and it refuses to send, which is the correct behaviour:

level=error msg="Async sent email 0 succeed, not send emails: admin@heatware.test
err: failed to send email: gomail: MandatoryStartTLS required, but SMTP server does not support STARTTLS"

Against the STARTTLS listener using a self-signed certificate with skip_verify = false, delivery fails with tls: failed to verify certificate: x509: certificate signed by unknown authority. Flipping skip_verify = true delivers. That flag turns off certificate chain and hostname checking, which is why the block at the top of this page leaves it false.

What actually arrives

With from_address = grafana@heatware.test, from_name = Grafana Local and X-Heatware-Verify = verify-run under [smtp.static_headers], this is the message mailpit received:

Return-Path: <grafana@heatware.test>
MIME-Version: 1.0
Date: Sun, 09 Aug 2026 22:57:55 -0500
X-Heatware-Verify: verify-run
From: "Grafana Local" <grafana@heatware.test>
To: admin@heatware.test
Subject: Reset your Grafana password - Admin
Message-ID: <531c17cd-7f1b-4b4f-8eb5-5ff3a1d976e6@heatware.test>

The Message-ID domain is derived from from_address, so setting it to something your domain does not own is visible to receiving servers. Static header keys must be in canonical MIME form (X-Foo-Bar); a lowercase key stops Grafana from starting rather than being skipped.

The failure that logs nothing

“Grafana silently logs and drops” is usually said about SMTP being turned off. That is the one case where Grafana is loud. With enabled = false, the reset endpoint returns HTTP 500 and names the problem:

{"message":"Failed to send email"}
error="SMTP not configured, check your grafana.ini config file's [smtp] section"

The silence begins once enabled = true and the transport is broken. Grafana queues the message and answers the HTTP request before dialling the server, so every broken configuration returns HTTP 200 {"message":"Email sent"} in about 30 milliseconds and delivers nothing. A bad STARTTLS policy or a rejected certificate at least leaves the one level=error line shown above.

The worst case leaves no line at all. Point Grafana at a port that expects TLS immediately — the mistake you make by picking a non-standard implicit-TLS port instead of 465 — and the plaintext dial hangs waiting for a banner that never comes. Repeat the send and the queue fills, and then the API itself stops answering:

    send # 9: HTTP 200  elapsed 0.03s
    send #10: HTTP 200  elapsed 0.03s
    send #11: HTTP 000  elapsed 8.05s
    send #12: HTTP 000  elapsed 8.05s
    send #13: HTTP 000  elapsed 8.07s
    send #14: HTTP 000  elapsed 8.05s

HTTP 000 is curl reporting its own timeout: the request never came back. Grafana’s notification queue holds ten messages, so with one more stuck in the hung dial you get eleven accepted sends and then the endpoint blocks. Across all fourteen sends the Grafana log contained zero lines matching Async sent email or failed to send email. If mail is broken and your log is clean, stop reading the log and check whether the port speaks plaintext, with the nc command above. That fourteen-send run is one of the checks in grafana-smtp-email-configuration.sh, which starts its own scratch Grafana and mailpit listeners on high ports.

Testing it without the UI

The old scripted test endpoint is gone. Grafana 13 answers it with 410 and names its replacement:

$ curl -X POST .../api/alertmanager/grafana/config/api/v1/receivers/test
{"message":"This endpoint has been removed. Please use
`/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{uid}/test` instead."}

For single-org OSS the namespace is default; asking for org-1 returns use default rather than org-1. The password-reset endpoint used throughout this article is simpler for a smoke test because it needs no receiver to exist first.

Your relay and TLS setup may differ

No authenticated SMTP, no real relay, no DKIM or SPF alignment, no implicit TLS on port 465 itself, no cert_file/key_file client certificates, and no enable_tracing. The STARTTLS, skip_verify and queue behaviour above is first-hand on 13.1.3; anything about your provider’s relay is not.

Photo of author
Sudhir P. founded HeatWare.com in 1999 and has built and operated it full-stack ever since; it is now used by more than 88,000 people. He writes here about the PostgreSQL, MySQL, Linux and DevOps work that keeps it running. Articles are rewritten only after the commands in them have actually been run, and the verification scripts are published alongside them so anyone can check the claims. Reach him at blog@heatware.net.