homelab-optimized/docs/services/matrix/SMTP.md

SMTP Email Configuration

Guide for configuring email delivery for Mastodon and Mattermost.

Gmail SMTP Setup

Prerequisites

1. Google account with 2-Factor Authentication enabled
2. App Password generated for "Mail"

Generate Gmail App Password

1. Go to Google Account Security
2. Enable 2-Step Verification if not already enabled
3. Go to App Passwords
4. Select "Mail" and your device
5. Click "Generate"
6. Copy the 16-character password

Mastodon Configuration

Edit /opt/mastodon/.env.production:

# SMTP Configuration (Gmail)
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_LOGIN=your-email@example.com
SMTP_PASSWORD="REDACTED_PASSWORD"
SMTP_AUTH_METHOD=plain
SMTP_OPENSSL_VERIFY_MODE=none
SMTP_ENABLE_STARTTLS=auto
SMTP_FROM_ADDRESS="Mastodon <notifications@mastodon.vish.gg>"

Apply changes:

cd /opt/mastodon && docker compose restart

Test Email Delivery

# Send test email
cd /opt/mastodon
docker compose exec web bin/tootctl accounts modify vish --confirm

# Or trigger password reset
# Go to login page and click "Forgot password"

Mattermost Email Configuration

Edit /opt/mattermost/config/config.json:

{
  "EmailSettings": {
    "EnableSignUpWithEmail": true,
    "EnableSignInWithEmail": true,
    "EnableSignInWithUsername": true,
    "SendEmailNotifications": true,
    "RequireEmailVerification": false,
    "FeedbackName": "Mattermost",
    "FeedbackEmail": "notifications@mm.crista.love",
    "SMTPUsername": "your-email@example.com",
    "SMTPPassword": "your_16_char_app_password",
    "SMTPServer": "smtp.gmail.com",
    "SMTPPort": "587",
    "ConnectionSecurity": "STARTTLS",
    "SendPushNotifications": true
  }
}

Restart Mattermost:

docker restart mattermost

Alternative: SendGrid

Setup

1. Create SendGrid account at https://sendgrid.com
2. Generate API key with "Mail Send" permission

Mastodon Configuration

SMTP_SERVER=smtp.sendgrid.net
SMTP_PORT=587
SMTP_LOGIN=apikey
SMTP_PASSWORD="REDACTED_PASSWORD"
SMTP_AUTH_METHOD=plain
SMTP_OPENSSL_VERIFY_MODE=peer
SMTP_ENABLE_STARTTLS=auto
SMTP_FROM_ADDRESS="Mastodon <notifications@mastodon.vish.gg>"

Alternative: Mailgun

Setup

1. Create Mailgun account at https://mailgun.com
2. Verify your domain
3. Get SMTP credentials

Mastodon Configuration

SMTP_SERVER=smtp.mailgun.org
SMTP_PORT=587
SMTP_LOGIN=postmaster@mg.yourdomain.com
SMTP_PASSWORD="REDACTED_PASSWORD"
SMTP_AUTH_METHOD=plain
SMTP_OPENSSL_VERIFY_MODE=peer
SMTP_ENABLE_STARTTLS=auto
SMTP_FROM_ADDRESS="Mastodon <notifications@mastodon.vish.gg>"

Troubleshooting

Check SMTP Connection

# Test from container
docker compose exec web bash -c "echo 'test' | openssl s_client -connect smtp.gmail.com:587 -starttls smtp"

Check Sidekiq Mail Queue

# View failed email jobs
docker compose exec web bin/tootctl sidekiq status

Common Errors

"Username and Password not accepted"

• Verify App Password is correct (not your regular password)
• Ensure 2FA is enabled on Google account
• Check no extra spaces in password

"Connection refused"

• Firewall blocking outbound port 587
• Try port 465 with SSL instead

"Certificate verify failed"

• Set SMTP_OPENSSL_VERIFY_MODE=none (less secure)
• Or ensure CA certificates are up to date

Gmail-Specific Issues

"Less secure app access"

• Not needed when using App Passwords
• App Passwords bypass this requirement

"Critical security alert"

• Normal for first connection from new IP
• Confirm it was you in Google Security settings

Email Content Customization

Mastodon

Email templates are in the Mastodon source code. Custom templates require forking.

Mattermost

Edit in System Console → Site Configuration → Customization

• Support Email
• Notification Footer
• Custom Branding

SPF/DKIM/DMARC

For better deliverability, configure DNS records:

SPF Record

TXT @ "v=spf1 include:_spf.google.com ~all"

Note on Gmail Sending

When using Gmail SMTP, emails are sent "via gmail.com" which has good deliverability. Custom domain email requires additional DNS setup.