179 lines
4.2 KiB
Markdown
179 lines
4.2 KiB
Markdown
# 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.
|