# 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](https://myaccount.google.com/security)
2. Enable 2-Step Verification if not already enabled
3. Go to [App Passwords](https://myaccount.google.com/apppasswords)
4. Select "Mail" and your device
5. Click "Generate"
6. Copy the 16-character password

### Mastodon Configuration

Edit `/opt/mastodon/.env.production`:

```env
# 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:
```bash
cd /opt/mastodon && docker compose restart
```

### Test Email Delivery

```bash
# 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`:

```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:
```bash
docker restart mattermost
```

## Alternative: SendGrid

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

### Mastodon Configuration
```env
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
```env
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
```bash
# 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
```bash
# 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.