🚨 Grafana Error Guide: 'SMTP not configured' — Fix Grafana Email Alerts and Invites

Overview

Grafana raises this whenever it tries to send email — an alert notification, a user invite, or a scheduled report — but the SMTP subsystem is disabled or unconfigured. The API/UI response and log read:

SMTP not configured, check your grafana.ini config file's [smtp] section

When SMTP is enabled but wrong, you get a delivery-time variant instead:

Failed to send notification ... error="dial tcp 10.0.0.5:587: connect: connection refused"

The first message means Grafana never even attempted delivery because [smtp] enabled = false (the default). Nothing about your contact point is broken — the mail transport itself is off.

Symptoms

• Testing an email contact point returns SMTP not configured.
• User invitations show “sent” in the UI but no email ever arrives.
• Scheduled reports (Enterprise) fail with the same message.
• Alert notifications to Slack/PagerDuty work, but email specifically fails.
• The Grafana log shows the message at startup or on the first send attempt.

Common Root Causes

• [smtp] enabled = false — the default; SMTP is off until explicitly turned on.
• Missing host/from_address so even an enabled block can’t build a connection or a valid sender.
• Wrong host:port or transport — using 465 (implicit TLS) config against a 587 (STARTTLS) server or vice versa.
• Auth required but user/password unset, so the relay rejects the message.
• Environment override not applied — config set in the wrong file, or env vars (GF_SMTP_ENABLED) not passed to the container.
• TLS/cert mismatch to the relay (self-signed CA, skip_verify needed for an internal relay).

Diagnostic Workflow

1. Confirm SMTP is actually enabled. Grafana exposes effective settings; check the running config, not just the file:

# Grep the config Grafana actually loaded
grep -A15 '^\[smtp\]' /etc/grafana/grafana.ini

# For containers, confirm the env overrides are present
docker exec grafana env | grep -i GF_SMTP

If enabled isn’t true, that’s the whole cause.

2. Read the log at send time. Trigger a test and watch:

journalctl -u grafana-server -f | grep -i 'smtp\|mail\|notification'

SMTP not configured = disabled; connection refused/timeout = enabled but wrong host/port/firewall; x509/tls = cert trust.

3. Configure the [smtp] section. Minimal working STARTTLS config in grafana.ini:

[smtp]
enabled = true
host = smtp.example.com:587
user = grafana@example.com
password = ${SMTP_PASSWORD}
from_address = grafana@example.com
from_name = Grafana
startTLS_policy = MandatoryStartTLS
skip_verify = false

Or via environment variables for a container:

GF_SMTP_ENABLED=true
GF_SMTP_HOST=smtp.example.com:587
GF_SMTP_USER=grafana@example.com
GF_SMTP_PASSWORD=...
GF_SMTP_FROM_ADDRESS=grafana@example.com

4. Restart and send a test. Use the built-in email test on a contact point, or the API:

sudo systemctl restart grafana-server

curl -s -X POST -H "Authorization: Bearer $GRAFANA_TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:3000/api/admin/settings | jq '.smtp'

5. Verify the relay is reachable from the Grafana host if delivery still fails:

# Confirm the SMTP port is open from Grafana's host
nc -vz smtp.example.com 587
openssl s_client -starttls smtp -connect smtp.example.com:587 </dev/null | head

Example Root Cause Analysis

A team wired up an email contact point for critical alerts and tested it — the UI immediately returned SMTP not configured, check your grafana.ini config file's [smtp] section. Slack alerts worked fine, so they assumed the contact point was misconfigured and rebuilt it twice with no change.

The contact point was never the issue. Grafana ran in Kubernetes with settings injected as env vars, and the Helm values set smtp.host and smtp.from_address but left smtp.enabled unset — so GF_SMTP_ENABLED defaulted to false. docker exec ... env | grep GF_SMTP showed host present, enabled absent.

Fix: set smtp.enabled: true in the Helm values, which rendered GF_SMTP_ENABLED=true, and restarted the pod. The test email delivered immediately. The lesson: SMTP not configured is about the transport being disabled, never about the contact point.

Prevention Best Practices

• Explicitly set enabled = true in every environment; don’t rely on host/from being enough.
• Store the SMTP password as a secret / env var, referenced with ${SMTP_PASSWORD}, never inline in committed config.
• Match the transport to the port — STARTTLS on 587, implicit TLS on 465 — and set startTLS_policy accordingly.
• Send a test email as part of provisioning so a disabled or unreachable relay is caught before a real alert fires.
• Alert on the log pattern SMTP not configured / Failed to send notification so email breakage is noticed.
• Add a non-email fallback (Slack/PagerDuty) on critical contact points so an SMTP outage never fully silences alerting.

Quick Command Reference

# Check the loaded SMTP config
grep -A15 '^\[smtp\]' /etc/grafana/grafana.ini
docker exec grafana env | grep -i GF_SMTP

# Watch send attempts
journalctl -u grafana-server -f | grep -i 'smtp\|notification'

# Inspect effective settings via API
curl -s -H "Authorization: Bearer $GRAFANA_TOKEN" http://localhost:3000/api/admin/settings | jq '.smtp'

# Verify relay reachability
openssl s_client -starttls smtp -connect smtp.example.com:587 </dev/null | head

Conclusion

SMTP not configured means Grafana’s mail transport is disabled — the default — not that your contact point is broken. Confirm [smtp] enabled = true in the effective config (including container env overrides), set host, sender, auth, and the correct TLS policy, then send a test email. Match the transport to the port, keep credentials in secrets, and always pair critical email alerts with a non-email fallback.