docs: update Mailgun configuration with correct sandbox domain
- Update domain to sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org - Set test email to psbailey31@gmail.com - Add comprehensive Mailgun setup guide - Document sandbox authorization requirements - Create email testing script - Update troubleshooting documentation Note: Sandbox domains require recipient authorization in Mailgun dashboard
This commit is contained in:
231
server/MAILGUN_SETUP.md
Normal file
231
server/MAILGUN_SETUP.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# Mailgun Email Setup Guide
|
||||
|
||||
## Current Configuration
|
||||
|
||||
- **API Key**: `dd27be7a81dd7b0980ada31fec9a9bd9-e80d8b76-fd80c63b`
|
||||
- **Domain**: `sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org`
|
||||
- **From Email**: `Beach Litter Platform <noreply@sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org>`
|
||||
|
||||
## Sandbox Domain Limitations
|
||||
|
||||
Mailgun sandbox domains have restrictions:
|
||||
- ✅ Free to use for testing
|
||||
- ❌ Can only send to **authorized recipients**
|
||||
- ❌ Limited to 300 emails per day
|
||||
- ❌ Emails may be marked as spam more often
|
||||
|
||||
## Step-by-Step: Authorize Recipients
|
||||
|
||||
### 1. Access Mailgun Dashboard
|
||||
|
||||
Go to: https://app.mailgun.com/
|
||||
|
||||
### 2. Navigate to Your Domain
|
||||
|
||||
1. Click on **"Sending"** in the left sidebar
|
||||
2. Click on **"Domains"**
|
||||
3. Select your sandbox domain: `sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org`
|
||||
|
||||
### 3. Add Authorized Recipients
|
||||
|
||||
1. Scroll down to the **"Authorized Recipients"** section
|
||||
2. Enter the email address you want to authorize (e.g., `psbailey31@gmail.com`)
|
||||
3. Click **"Invite"**
|
||||
|
||||
### 4. Confirm Authorization
|
||||
|
||||
1. The recipient will receive an email from Mailgun
|
||||
2. Subject: "Mailgun Sandbox Domain Authorization"
|
||||
3. They must click the confirmation link in the email
|
||||
4. Once confirmed, you can send emails to that address
|
||||
|
||||
### 5. Test Email Sending
|
||||
|
||||
Run the test script:
|
||||
|
||||
```bash
|
||||
cd server
|
||||
npx tsx src/scripts/testEmail.ts
|
||||
```
|
||||
|
||||
You should see:
|
||||
```
|
||||
✅ Test email sent successfully to psbailey31@gmail.com
|
||||
```
|
||||
|
||||
## Common Errors
|
||||
|
||||
### Error: "Forbidden"
|
||||
|
||||
**Cause**: Recipient email is not authorized in sandbox domain
|
||||
|
||||
**Solution**:
|
||||
1. Add the email to authorized recipients in Mailgun dashboard
|
||||
2. Recipient must confirm the authorization email
|
||||
3. Wait a few minutes and try again
|
||||
|
||||
### Error: "Unauthorized"
|
||||
|
||||
**Cause**: Invalid API key
|
||||
|
||||
**Solution**:
|
||||
1. Verify API key in `.env` file
|
||||
2. Check for extra spaces or quotes
|
||||
3. Regenerate API key in Mailgun if needed
|
||||
|
||||
### Emails Going to Spam
|
||||
|
||||
**Cause**: Sandbox domains have lower reputation
|
||||
|
||||
**Solution**:
|
||||
1. For testing, check spam folder
|
||||
2. For production, use a verified custom domain
|
||||
3. Set up SPF and DKIM records
|
||||
|
||||
## Upgrading to Production
|
||||
|
||||
For production use, you should:
|
||||
|
||||
### 1. Add a Custom Domain
|
||||
|
||||
1. Go to Mailgun dashboard → Domains
|
||||
2. Click "Add New Domain"
|
||||
3. Enter your domain (e.g., `beachlitter.ie`)
|
||||
4. Follow DNS setup instructions
|
||||
|
||||
### 2. Verify Domain
|
||||
|
||||
Add these DNS records to your domain:
|
||||
|
||||
```
|
||||
TXT @ v=spf1 include:mailgun.org ~all
|
||||
TXT k1._domainkey [provided by Mailgun]
|
||||
CNAME email mailgun.org
|
||||
```
|
||||
|
||||
### 3. Update Configuration
|
||||
|
||||
Update `.env`:
|
||||
|
||||
```env
|
||||
MAILGUN_DOMAIN="beachlitter.ie"
|
||||
FROM_EMAIL="Beach Litter Platform <noreply@beachlitter.ie>"
|
||||
```
|
||||
|
||||
### 4. Benefits of Custom Domain
|
||||
|
||||
- ✅ Send to any email address (no authorization needed)
|
||||
- ✅ Better email deliverability
|
||||
- ✅ Professional sender address
|
||||
- ✅ Higher sending limits
|
||||
- ✅ Better spam score
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] API key is correct in `.env`
|
||||
- [ ] Domain is correct in `.env`
|
||||
- [ ] Test email is authorized in Mailgun dashboard
|
||||
- [ ] Test email confirmation link was clicked
|
||||
- [ ] Test script runs successfully
|
||||
- [ ] Email appears in inbox (or spam folder)
|
||||
- [ ] Email formatting looks correct
|
||||
- [ ] Links in email work correctly
|
||||
|
||||
## Email Templates
|
||||
|
||||
The system sends two types of emails:
|
||||
|
||||
### 1. Simple Text Email
|
||||
|
||||
Plain text with basic formatting, used for:
|
||||
- Test emails
|
||||
- System notifications
|
||||
|
||||
### 2. HTML Notification Email
|
||||
|
||||
Formatted HTML with:
|
||||
- Beach Litter Platform branding
|
||||
- Professional styling
|
||||
- Call-to-action buttons
|
||||
- Responsive design
|
||||
|
||||
Used for:
|
||||
- New report notifications
|
||||
- New event notifications
|
||||
- Event reminders
|
||||
- Report verification notifications
|
||||
|
||||
## Monitoring Email Delivery
|
||||
|
||||
### Mailgun Dashboard
|
||||
|
||||
View email statistics:
|
||||
1. Go to https://app.mailgun.com/
|
||||
2. Click "Analytics" → "Overview"
|
||||
3. See sent, delivered, opened, clicked metrics
|
||||
|
||||
### Server Logs
|
||||
|
||||
Check application logs for:
|
||||
- Email sending attempts
|
||||
- Success/failure messages
|
||||
- Error details
|
||||
|
||||
```bash
|
||||
# View recent logs
|
||||
tail -f server.log | grep EMAIL
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
### Sandbox Domain
|
||||
- 300 emails per day
|
||||
- 100 emails per hour
|
||||
|
||||
### Verified Domain
|
||||
- 10,000 emails per month (free tier)
|
||||
- Higher limits available with paid plans
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
1. **Check Mailgun Status**: https://status.mailgun.com/
|
||||
2. **Review Logs**: Check server logs for detailed errors
|
||||
3. **Mailgun Support**: https://help.mailgun.com/
|
||||
4. **Documentation**: https://documentation.mailgun.com/
|
||||
|
||||
## Alternative: Using a Different Email Service
|
||||
|
||||
If you prefer a different email service, you can modify `server/src/services/emailService.ts`:
|
||||
|
||||
### SendGrid
|
||||
```typescript
|
||||
import sgMail from '@sendgrid/mail';
|
||||
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
|
||||
```
|
||||
|
||||
### AWS SES
|
||||
```typescript
|
||||
import AWS from 'aws-sdk';
|
||||
const ses = new AWS.SES({ region: 'us-east-1' });
|
||||
```
|
||||
|
||||
### Nodemailer (SMTP)
|
||||
```typescript
|
||||
import nodemailer from 'nodemailer';
|
||||
const transporter = nodemailer.createTransport({
|
||||
host: 'smtp.gmail.com',
|
||||
port: 587,
|
||||
auth: { user: 'email', pass: 'password' }
|
||||
});
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
The notification system is configured and ready to use. For testing:
|
||||
1. Authorize recipient emails in Mailgun dashboard
|
||||
2. Run the test script
|
||||
3. Check inbox (and spam folder)
|
||||
|
||||
For production, upgrade to a verified custom domain for better deliverability and no authorization requirements.
|
||||
Reference in New Issue
Block a user