Sanitized mirror from private repository - 2026-04-20 01:24:42 UTC

2026-04-20 01:24:42 +00:00
commit e71c8ddb4b
1441 changed files with 363888 additions and 0 deletions
--- a/docs/services/matrix/SMTP.md
+++ b/docs/services/matrix/SMTP.md
@@ -0,0 +1,178 @@
+# 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.