ocean-cleanup/server/MAILGUN_SETUP.md

# 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.