Where to Setup Grafana SMTP Settings: Complete Configuration Guide

Configuring email notifications is essential for effective monitoring with Grafana. Whether you need alerts for system outages, threshold breaches, or scheduled reports, understanding where to setup Grafana SMTP settings is the first step. This guide covers everything from locating the configuration file to testing your email setup.

Where Are Grafana SMTP Settings Located?

Grafana SMTP settings are configured in the main configuration file, typically named grafana.ini. The exact location depends on your installation method:

Installation Method	Configuration File Location
Linux (apt/yum)	/etc/grafana/grafana.ini
Docker	/etc/grafana/grafana.ini (inside container)
Windows	<install_dir>\conf\defaults.ini or custom.ini
macOS (Homebrew)	/usr/local/etc/grafana/grafana.ini
Binary download	<working_dir>/conf/custom.ini
Kubernetes Helm	ConfigMap or values.yaml

For custom installations, you can specify a different configuration path using the --config flag when starting Grafana:

grafana-server --config=/path/to/custom.ini

Basic SMTP Configuration

Open your grafana.ini file and locate the [smtp] section. By default, most settings are commented out with semicolons. Here’s a basic configuration:

[smtp]
enabled = true
host = smtp.example.com:587
user = alerts@example.com
password = your-password-here
from_address = alerts@example.com
from_name = Grafana Alerts

Configuration Options Explained

Setting	Description	Default
enabled	Enable/disable SMTP	false
host	SMTP server and port	localhost:25
user	SMTP authentication username	(empty)
password	SMTP authentication password	(empty)
cert_file	Path to TLS certificate	(empty)
key_file	Path to TLS private key	(empty)
skip_verify	Skip TLS certificate verification	false
from_address	Email sender address	admin@grafana.localhost
from_name	Email sender display name	Grafana
ehlo_identity	EHLO identity for SMTP	(empty)
startTLS_policy	TLS policy: OpportunisticStartTLS, MandatoryStartTLS, NoStartTLS	OpportunisticStartTLS

Password with Special Characters

If your password contains # or ;, wrap it with triple quotes:

password = """my#complex;password"""

Gmail SMTP Configuration

Gmail requires an App Password instead of your regular password. Here’s how to set it up:

Step 1: Generate Gmail App Password

1. Go to Google Account Security
2. Enable 2-Step Verification if not already enabled
3. Navigate to “App passwords”
4. Select “Mail” and your device
5. Click “Generate” and copy the 16-character password

Step 2: Configure Grafana

[smtp]
enabled = true
host = smtp.gmail.com:587
user = your-email@gmail.com
password = your-16-char-app-password
skip_verify = false
from_address = your-email@gmail.com
from_name = Grafana Alerts
startTLS_policy = MandatoryStartTLS

For Gmail with implicit TLS (port 465):

host = smtp.gmail.com:465
startTLS_policy = NoStartTLS

Microsoft 365 / Office 365 SMTP Configuration

For Microsoft 365, use SMTP AUTH with your organization’s credentials:

[smtp]
enabled = true
host = smtp.office365.com:587
user = alerts@yourdomain.com
password = your-password
from_address = alerts@yourdomain.com
from_name = Grafana Monitoring
startTLS_policy = MandatoryStartTLS

Note: Your Microsoft 365 admin may need to enable SMTP AUTH for your account in the Exchange admin center.

AWS SES SMTP Configuration

For Amazon Simple Email Service (SES):

[smtp]
enabled = true
host = email-smtp.us-east-1.amazonaws.com:587
user = YOUR_SMTP_USERNAME
password = YOUR_SMTP_PASSWORD
from_address = verified-email@yourdomain.com
from_name = Grafana Alerts
startTLS_policy = MandatoryStartTLS

Important: The from_address must be a verified email or domain in SES.

SendGrid SMTP Configuration

For SendGrid:

[smtp]
enabled = true
host = smtp.sendgrid.net:587
user = apikey
password = your-sendgrid-api-key
from_address = alerts@yourdomain.com
from_name = Grafana Monitoring
startTLS_policy = MandatoryStartTLS

Note: The username is literally apikey, and the password is your SendGrid API key.

Kubernetes Helm Chart Configuration

When deploying Grafana on Kubernetes using Helm, configure SMTP in your values.yaml:

grafana.ini:
  smtp:
    enabled: true
    host: smtp.example.com:587
    user: alerts@example.com
    password: your-password
    from_address: alerts@example.com
    from_name: Grafana Alerts
    startTLS_policy: MandatoryStartTLS

For sensitive data, use Kubernetes secrets:

envFromSecret: grafana-smtp-secret

Create the secret:

kubectl create secret generic grafana-smtp-secret \
  --from-literal=GF_SMTP_USER=alerts@example.com \
  --from-literal=GF_SMTP_PASSWORD=your-password

Docker Configuration

For Docker deployments, pass SMTP settings as environment variables:

docker run -d \
  -e GF_SMTP_ENABLED=true \
  -e GF_SMTP_HOST=smtp.gmail.com:587 \
  -e GF_SMTP_USER=your-email@gmail.com \
  -e GF_SMTP_PASSWORD=your-app-password \
  -e GF_SMTP_FROM_ADDRESS=your-email@gmail.com \
  -e GF_SMTP_FROM_NAME="Grafana Alerts" \
  grafana/grafana

Or in docker-compose.yml:

services:
  grafana:
    image: grafana/grafana:latest
    environment:
      - GF_SMTP_ENABLED=true
      - GF_SMTP_HOST=smtp.gmail.com:587
      - GF_SMTP_USER=your-email@gmail.com
      - GF_SMTP_PASSWORD=your-app-password
      - GF_SMTP_FROM_ADDRESS=your-email@gmail.com
      - GF_SMTP_FROM_NAME=Grafana Alerts

Managed Grafana SMTP Configuration

Amazon Managed Grafana

Amazon Managed Grafana supports SMTP configuration through the AWS console. However, email alerting requires additional setup with Amazon SES or external SMTP providers.

Azure Managed Grafana

For Azure Managed Grafana, configure SMTP through the Azure portal:

1. Navigate to your Managed Grafana workspace
2. Select Settings > Configuration > SMTP
3. Enable SMTP and enter your server details
4. Save the configuration

Supported TLS policies for Azure Managed Grafana:

• OpportunisticStartTLS (default): Encrypts if STARTTLS is supported
• MandatoryStartTLS: Requires STARTTLS
• NoStartTLS: No encryption (not recommended)

Testing Your SMTP Configuration

After configuring SMTP, test it through Grafana’s UI:

1. Navigate to Alerting > Contact points
2. Click New contact point or edit an existing one
3. Select Email as the contact point type
4. Enter a test email address
5. Click Test to send a test notification

If successful, you’ll receive an email with subject [FIRING:1] (TestAlert Grafana).

Creating Email Alert Contact Points

Once SMTP is configured, create contact points for your alerts:

# Example contact point configuration
apiVersion: 1
contactPoints:
  - orgId: 1
    name: email-team
    receivers:
      - uid: email-1
        type: email
        settings:
          addresses: team@example.com;oncall@example.com
          singleEmail: false

Key settings for email contact points:

Setting	Description
addresses	Semicolon-separated email addresses
singleEmail	Send single email to all recipients (true) or individual emails (false)
message	Custom email body (supports templating)

Troubleshooting Common SMTP Issues

Error: “SMTP not configured”

Cause: SMTP is disabled or misconfigured.

Solution: Verify enabled = true in the [smtp] section and restart Grafana:

sudo systemctl restart grafana-server

Error: “Authentication failed”

Causes:

• Incorrect username or password
• Gmail: Using regular password instead of App Password
• Office 365: SMTP AUTH not enabled

Solutions:

• Double-check credentials
• For Gmail, generate an App Password
• For Office 365, enable SMTP AUTH in Exchange admin center

Error: “Connection refused” or “Connection timed out”

Causes:

• Wrong SMTP host or port
• Firewall blocking outbound SMTP traffic
• SMTP server not reachable

Solutions:

• Verify host and port settings
• Test connectivity: telnet smtp.gmail.com 587
• Check firewall rules allow outbound ports 25, 465, or 587

Error: “Certificate verify failed”

Cause: TLS certificate validation failure.

Solutions:

For testing only (not recommended for production):

skip_verify = true

For production, ensure your system trusts the SMTP server’s CA:

# Ubuntu/Debian
sudo apt-get install ca-certificates
sudo update-ca-certificates

Error: “Sender address rejected”

Cause: The from_address is not authorized to send through the SMTP server.

Solutions:

• Use an email address from a verified domain
• For AWS SES, verify the sender email or domain
• Check your SMTP provider’s sender policies

Security Best Practices

1. Use TLS: Always use startTLS_policy = MandatoryStartTLS or port 465 for implicit TLS
2. App Passwords: Never use primary account passwords; use app-specific passwords
3. Secrets Management: Store SMTP credentials in environment variables or secrets managers, not plain text
4. Restrict Access: Limit who can modify Grafana configuration files
5. Audit Logging: Enable Grafana audit logging to track configuration changes

For organizations needing help with Grafana alerting setup, our Grafana consulting services and Grafana support team can assist with implementation and troubleshooting.

Environment Variables Reference

All SMTP settings can be configured via environment variables using the GF_SMTP_ prefix:

Environment Variable	Configuration Equivalent
GF_SMTP_ENABLED	smtp.enabled
GF_SMTP_HOST	smtp.host
GF_SMTP_USER	smtp.user
GF_SMTP_PASSWORD	smtp.password
GF_SMTP_CERT_FILE	smtp.cert_file
GF_SMTP_KEY_FILE	smtp.key_file
GF_SMTP_SKIP_VERIFY	smtp.skip_verify
GF_SMTP_FROM_ADDRESS	smtp.from_address
GF_SMTP_FROM_NAME	smtp.from_name
GF_SMTP_EHLO_IDENTITY	smtp.ehlo_identity
GF_SMTP_STARTTLS_POLICY	smtp.startTLS_policy

Summary

Understanding where to setup Grafana SMTP settings is crucial for enabling email alerts. The configuration lives in grafana.ini (or equivalent for your deployment), specifically in the [smtp] section. Key points to remember:

• Location: /etc/grafana/grafana.ini for most Linux installations
• Enable SMTP: Set enabled = true
• Use TLS: Configure startTLS_policy = MandatoryStartTLS
• Test thoroughly: Use Grafana’s built-in test feature before relying on alerts
• Secure credentials: Use environment variables or secrets for passwords

For production Grafana deployments with complex alerting requirements, proper SMTP configuration ensures your team receives critical notifications when they matter most.

---

Need Help with Grafana Alerting?

Our Grafana consulting team helps organizations implement robust alerting with proper SMTP configuration, contact point routing, and notification policies. From initial setup to advanced alert management, we ensure your monitoring delivers actionable notifications.

Book a free 30-minute consultation to discuss your Grafana alerting requirements.