Email configuration

Set up email to enable password resets, user invitations, dashboard subscriptions, and alerts in Metabase.

Email configuration is essential for Metabase to send notifications, password resets, and onboard new users. Both admins and users with settings access can configure email.

Metabase uses email for:

• Password reset requests
• New user invitations
• Dashboard subscriptions
• Alerts
• Admin notifications

Accessing email settings

Navigate to Admin > Settings > Email to configure your email setup.

Metabase Cloud email

Default SMTP server

Metabase Cloud provides a managed email server by default—no configuration required.

1. Automatic setup

   Email works immediately on new Metabase Cloud instances

2. Optional customization

   You can optionally configure:

   • Display name for emails (“from” name)
   • Reply-to email address

With the default server, emails are sent from a Metabase address. The from domain cannot be changed without using a custom SMTP server.

Custom SMTP server on Metabase Cloud

Custom SMTP servers on Metabase Cloud are available on Pro and Enterprise plans.

Bring your own SMTP server to gain more control over email delivery.

Benefits of custom SMTP:

• Customize the from domain (useful for white-labeling)
• Avoid emails passing through third-party services
• Own IP reputation and monitoring
• Control auditing and logs
• Full compliance with email policies

1. Navigate to email settings

   Go to Admin > Settings > Email

2. Select custom server

   Click Set up a custom SMTP server

3. Configure SMTP settings

   Enter your SMTP server details (see configuration below)

4. Test configuration

   Send a test email to verify setup

5. Save settings

   Apply the configuration

You can toggle between the Metabase-managed server and your custom SMTP server at any time.

Self-hosted email configuration

For self-hosted Metabase instances, you must configure an SMTP server for email functionality.

SMTP configuration fields

1. SMTP host

   The address of your SMTP server (e.g., smtp.gmail.com, smtp.sendgrid.net)

2. SMTP port

   The port for outgoing email:

   • 465: SSL (recommended)
   • 587: TLS (recommended)
   • 2525: STARTTLS (recommended)
   • 25: Unencrypted (not recommended)
3. SMTP security

   Select the encryption protocol:

   • SSL: Secure Sockets Layer
   • TLS: Transport Layer Security (recommended)
   • STARTTLS: Opportunistic TLS
   • None: Unencrypted (not recommended)
4. SMTP username

   Your SMTP account username (usually your email address)

5. SMTP password

   Your SMTP account password or API key

6. From address

   The email address shown as the sender

7. Reply-to address

   Where replies should go (can be different from the from address)

Security recommendation: Always use SSL or TLS encryption for email security and account protection.

Whitelisting email addresses

If your email service has a whitelist, add your from address to ensure emails are delivered successfully.

Email provider configurations

Google Apps / Gmail

1. SMTP host

   smtp.gmail.com

2. SMTP port

   465

3. SMTP security

   SSL

4. Username

   Your full Google Apps email (e.g., [e-mail])

5. Password

   Your Google Apps password or app-specific password

6. From address

   Your Google Apps email address

Using app-specific passwords

If you have 2-factor authentication enabled on your Google account:

1. Go to Google Account Settings
2. Navigate to Security > 2-Step Verification > App passwords
3. Generate a new app password for Metabase
4. Use this generated password instead of your regular password

Amazon SES

1. Access AWS console

   Log in to AWS SES Console

2. Navigate to SMTP settings

   Click SMTP Settings in the navigation pane

3. Create SMTP credentials

   1. Select Create My SMTP Credentials
   2. Create a user in the dialog
   3. Click Create
4. View credentials

   Click Show User SMTP Credentials to view your credentials

5. Configure in Metabase

   Use the provided SMTP endpoint, port, username, and password

Amazon SES quotas: Check if email quotas apply to your account. Consider managing recipients using groups to stay within limits.

Typical Amazon SES settings:

• Host: email-smtp.us-east-1.amazonaws.com (varies by region)
• Port: 587 (TLS) or 465 (SSL)
• Security: TLS or SSL
• Username: Your SMTP username from AWS
• Password: Your SMTP password from AWS

Mandrill

1. Get credentials

   Log in to Mandrill and locate SMTP & API Info

2. SMTP host

   smtp.mandrillapp.com

3. SMTP port

   Any port supported by Mandrill: 587, 2525, or 465

4. Username

   Your Mandrill account email

5. Password

   Any active API key (not your Mandrill password)

Important: For Mandrill, use an active API key as the password, not your account password.

SendGrid

1. Create API key

   Generate an API key in SendGrid settings with full mail send access

2. SMTP host

   smtp.sendgrid.net

3. SMTP port

   587 (TLS recommended) or 465 (SSL)

4. Security

   TLS or SSL

5. Username

   apikey (literally the string “apikey”)

6. Password

   Your SendGrid API key

Office 365 / Microsoft 365

1. SMTP host

   smtp.office365.com

2. SMTP port

   587

3. Security

   STARTTLS

4. Username

   Your full Office 365 email address

5. Password

   Your Office 365 password

Advanced email settings

CC vs BCC recipients

By default, Metabase uses BCC (Blind Carbon Copy) to hide email recipients from each other.

When to use CC instead of BCC

Switch to CC (Carbon Copy) if:

• Your email provider blocks BCC emails
• You want recipients to see who else received the email
• Your organization requires visible recipient lists

With CC enabled, all recipients can see each other’s email addresses in subscriptions and alerts.

Configure this in Admin > Settings > Email > Recipient visibility.

Approved domains for notifications

Approved domains are available on Pro and Enterprise plans.

Restrict which external email addresses can receive alerts and dashboard subscriptions.

1. Navigate to email settings

   Go to Admin > Settings > Email

2. Configure approved domains

   Enter allowed domains in the Approved domains field

3. Save settings

   Apply the configuration

Configuration examples:

example.com

Allows any @example.com email address

example.com,partner.com,vendor.com

Allows multiple domains (comma-separated, no spaces)

Empty field allows all domains (default)

Important behaviors:

• Restrictions only apply to external recipients (people without Metabase accounts)
• Users with Metabase accounts can email each other regardless of domain
• People with row or column security cannot see email suggestions
• Existing subscriptions and alerts are not affected

Alternatively, set via environment variable:

MB_SUBSCRIPTION_ALLOWED_DOMAINS=example.com,partner.com

Suggested recipients

Configuring suggested recipients is available on Pro and Enterprise plans.

Control which users are suggested when creating subscriptions and alerts.

Options:

Suggest all users

Show all Metabase users as potential recipients when creating subscriptions and alerts.

Best for: Small teams with open collaboration

Only suggest users in the same groups

Only show users who share at least one group with the person creating the subscription/alert.

Best for: Organizations with department-based groups wanting to limit cross-department notifications

Don't show suggestions

Recipients must manually enter email addresses—no suggestions appear.

Best for: High-security environments or when working with external recipients

Users with row or column restrictions never see suggestions, regardless of this setting.

Testing email configuration

After configuring email settings, always test before relying on email functionality.

1. Configure SMTP

   Enter all required SMTP settings

2. Send test email

   Click Send test email button at the bottom of the form

3. Check inbox

   Verify the test email arrives in your inbox

4. Check spam folder

   If not received, check spam/junk folders

5. Verify settings

   If test fails, review SMTP credentials and network connectivity

Common test email failures

Authentication errors:

• Incorrect username or password
• 2FA enabled without app-specific password
• API key instead of password (or vice versa)

Connection errors:

• Firewall blocking SMTP port
• Incorrect host or port
• Wrong security protocol selected

Authorization errors:

• From address not authorized to send
• Account not verified with email provider
• Sending limits reached

Troubleshooting

Emails not being received

Check:

1. Test email configuration works
2. Emails aren’t in spam folders
3. From address is whitelisted
4. Recipient email addresses are correct
5. Email provider quotas haven’t been exceeded
6. Email logs for error messages

Authentication failures

Verify:

1. Username is correct format
2. Password/API key is current and accurate
3. For Gmail: App-specific password if using 2FA
4. For Mandrill: Using API key, not account password
5. For SendGrid: Username is literally “apikey”

Connection timeouts

Check:

1. Firewall allows outbound connections on SMTP port
2. Network can reach SMTP server
3. Correct port selected (465 for SSL, 587 for TLS)
4. Security protocol matches port
5. SMTP server is operational

Subscriptions not sending

Verify:

1. Email configuration is working
2. Subscription schedule is correct
3. Dashboard/question permissions are set correctly
4. Recipients have proper access
5. No email delivery errors in logs

Environment variables

For self-hosted deployments, configure email via environment variables:

MB_EMAIL_SMTP_HOST=smtp.example.com
MB_EMAIL_SMTP_PORT=587
MB_EMAIL_SMTP_SECURITY=tls
MB_EMAIL_SMTP_USERNAME=[e-mail]
MB_EMAIL_SMTP_PASSWORD=your-password
MB_EMAIL_FROM_ADDRESS=[e-mail]
MB_EMAIL_REPLY_TO=[e-mail]

See the complete list of environment variables.

Best practices

1. Use encrypted connections

   Always configure SSL or TLS encryption for security

2. Test thoroughly

   Verify email works with test emails and real subscriptions

3. Monitor deliverability

   Check email delivery rates and spam classifications

4. Configure reply-to

   Set a monitored reply-to address for user responses

5. Document configuration

   Maintain records of email setup for troubleshooting

6. Review approved domains

   Regularly audit approved domains for notifications

Related documentation

• Dashboard subscriptions
• Alerts configuration
• Notification permissions
• Slack setup
• Environment variables