Grafana ships with email disabled. Until you set the enabled flag in the SMTP section of the configuration and restart, no alert will ever reach an inbox and the interface will tell you SMTP is not configured.
This is one of those setups where every individual step is trivial and the whole thing still takes an afternoon, because the failure modes are silent and the configuration lives in a place people do not expect when running in a container.
Table of contents
- The configuration
- Docker and environment variables
- Provider-specific gotchas
- Testing without waiting for an alert
- Templates and the operational bit
- How this fits the rest of the stack
- FAQ
The configuration
Settings live in the SMTP section of the Grafana configuration file, typically named grafana.ini or custom.ini in the conf directory of the installation.
[smtp]
enabled = true
host = smtp.example.com:587
user = [email protected]
password = your-app-password
from_address = [email protected]
from_name = Grafana
startTLS_policy = OpportunisticStartTLS
skip_verify = falseThree fields cause most of the trouble. The enabled flag defaults to false and nothing works until it is true. The host field must include the port - a bare hostname fails, and the error does not always say why. And the from address usually has to be an address the SMTP provider considers authorised, which is frequently not the same as the login user.
On passwords containing special characters, wrap the value in triple quotes. Semicolons and hash characters are treated as comment markers in this file format, so a password containing either is silently truncated at that point and you get an authentication failure with a perfectly correct-looking config.
password = """p@ss;word#123"""After editing, restart Grafana. The configuration is read at startup and not watched.
sudo systemctl restart grafana-server
sudo systemctl status grafana-serverDocker and environment variables
In a container, editing the file inside the image is the wrong approach - it does not survive a restart. Grafana maps every configuration key to an environment variable, and that is the right mechanism.
The naming rule is a fixed prefix, then the section name, then the key, all uppercase with underscores.
services:
grafana:
image: grafana/grafana:11.3.0
ports:
- "3000:3000"
environment:
GF_SMTP_ENABLED: "true"
GF_SMTP_HOST: "smtp.example.com:587"
GF_SMTP_USER: "[email protected]"
GF_SMTP_PASSWORD: "${SMTP_PASSWORD}"
GF_SMTP_FROM_ADDRESS: "[email protected]"
GF_SMTP_FROM_NAME: "Grafana"
GF_SMTP_STARTTLS_POLICY: "OpportunisticStartTLS"
volumes:
- grafana-data:/var/lib/grafana
volumes:
grafana-data:Note the quoted true. Boolean-looking values in YAML can be converted to a native boolean and then rendered in a form Grafana does not accept. Quoting removes the ambiguity.
Keep the password out of the compose file itself - reference it from the environment or a secrets file so the credential is not sitting in a committed file. Environment-variable configuration overrides the file, so you do not need both.
Provider-specific gotchas
Most failures are the provider’s rules rather than Grafana’s configuration.
Consumer mail providers. Nearly all of them now require an app-specific password rather than your account password when two-factor authentication is on, and many block plain password authentication entirely. Generate a dedicated app password and use that.
Transactional email services. These usually want a fixed literal username - often something like apikey - with the actual key as the password. Using your account email as the username fails with a confusing authentication error.
Domain verification. Transactional providers reject messages from an unverified sending domain. This produces a successful SMTP connection followed by a rejected message, which is a particularly annoying failure because the connection test passes.
Port choice. Port 587 with STARTTLS is the modern default. Port 465 is implicit TLS and needs the STARTTLS policy adjusted accordingly. Port 25 is blocked outbound by most hosting providers and cloud platforms, so if you are on 25 and nothing sends, that is likely the entire explanation.
Internal relays. An internal SMTP relay may use a self-signed certificate. Setting skip verify to true works and disables certificate validation, so only do it on a network you control and never toward an external provider.
Testing without waiting for an alert
Do not test by waiting for a real alert to fire. Use the contact point test, which sends immediately and reports the error inline.
- Go to Alerting, then Contact points.
- Create or edit an Email contact point and enter a recipient address.
- Use the Test button.
- Read the error if it fails - it is usually the actual SMTP error rather than a generic message.
If the test button is missing or the interface says SMTP is not configured, the enabled flag is not taking effect. Check that you restarted, and in a container check the variables actually reached the process.
# What the running container actually sees
docker exec grafana env | grep GF_SMTP
# Grafana's own logs during a send attempt
docker logs -f grafana 2>&1 | grep -i smtp
# On a package install
sudo journalctl -u grafana-server -f | grep -i smtpTo rule out Grafana entirely, test the credentials from the same host with a separate mail client. If that fails too, the problem is the network or the provider, and no amount of configuration editing will help.
# Is the port even reachable from this host?
nc -zv smtp.example.com 587Templates and the operational bit
Once mail sends, the next problem is that the default alert email is not very informative. Grafana supports message templating on contact points, and a small amount of effort here pays off during an incident.
Include the things a person needs to act: which alert, which instance or service, the current value against the threshold, when it started, and a link back to the dashboard. An email that says an alert fired without saying where is an email that generates a question rather than an action.
Two operational habits worth adopting. Set up notification grouping so a hundred instances of one problem produce one email rather than a hundred - the alternative trains people to filter your alerts into a folder they never open. And route by severity, so that things needing attention now and things needing attention this week do not arrive through the same channel.
Finally, be aware that email is a poor channel for anything genuinely urgent. Delivery is best-effort and can be delayed by minutes. For alerts that need a response within minutes, email should be the record rather than the notification.
How this fits the rest of the stack
Alerting only helps if the thing being alerted on is visible in the first place, and for a deployed application that starts with build logs and runtime logs in the same place. On RunxBuild a service gives you both per deploy, alongside metrics and rollback to the previous version. The RunxBuild hosting calculator shows what the service and its managed database cost as separate line items, so the environment you are monitoring has a known price.
Useful related references:
- Port 587: The SMTP Submission Port, and Why Your App Should Use It
- SMTP Ports Explained: 25, 465, 587, and Which One You Should Use
- Services on RunxBuild
FAQ
Why is Grafana not sending emails?
Most often the enabled flag in the SMTP configuration section is still false, or Grafana was not restarted after the change. The next most common causes are a host value missing its port, a from address the provider will not accept, or a password containing a semicolon or hash that was truncated as a comment.
Where is the Grafana SMTP configuration file?
It is the SMTP section of grafana.ini or custom.ini, in the conf directory of your Grafana installation. In Docker, do not edit the file inside the image - set the equivalent environment variables instead, using the prefix plus section plus key naming convention.
How do I set Grafana SMTP settings in Docker?
Use environment variables that map to the configuration keys - the fixed Grafana prefix, then SMTP, then the key name, uppercase with underscores. Quote boolean values so YAML does not convert them into a form Grafana rejects, and keep the password out of the compose file itself.
Why does my SMTP password not work in grafana.ini?
Semicolons and hash characters are comment markers in that file format, so a password containing either is silently truncated at that character. Wrap the value in triple quotes to preserve it, or set it through an environment variable instead.
How do I test Grafana email without triggering an alert?
Go to Alerting, then Contact points, create or edit an Email contact point, and use the Test button. It sends immediately and usually surfaces the underlying SMTP error inline, which is far more useful than waiting for a real alert to fire.