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:

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:

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

# 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

import sgMail from '@sendgrid/mail';
sgMail.setApiKey(process.env.SENDGRID_API_KEY);

AWS SES

import AWS from 'aws-sdk';
const ses = new AWS.SES({ region: 'us-east-1' });

Nodemailer (SMTP)

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.