ocean-cleanup/server/NOTIFICATION_QUICK_START.md

Notification System - Quick Start Guide

🚀 Get Started in 3 Steps

Step 1: Authorize Your Email in Mailgun

1. Go to https://app.mailgun.com/
2. Navigate to: Sending → Domains → sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org
3. Scroll to "Authorized Recipients"
4. Add your email: psbailey31@gmail.com
5. Click "Invite"
6. Check your email and click the confirmation link

Step 2: Test Email Delivery

cd server
npx tsx src/scripts/testEmail.ts

Expected output:

✅ Test email sent successfully to psbailey31@gmail.com
✅ Notification email sent successfully to psbailey31@gmail.com

Check your inbox (and spam folder)!

Step 3: Test Full Notification System

cd server
npx tsx src/scripts/testNotifications.ts

This tests:

• ✅ Email service connection
• ✅ Notification creation
• ✅ Area-of-interest matching
• ✅ Mark as read functionality
• ✅ Event reminders

📧 Configuration

Already configured in .env:

MAILGUN_API_KEY="dd27be7a81dd7b0980ada31fec9a9bd9-e80d8b76-fd80c63b"
MAILGUN_DOMAIN="sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org"
FROM_EMAIL="Beach Litter Platform <noreply@sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org>"
TEST_EMAIL="psbailey31@gmail.com"

🔔 How It Works

For Users

1. Set Areas of Interest:

   • Go to Profile → Notification Settings
   • Add locations with radius (1-50km)
   • Enable email/in-app notifications

2. Receive Notifications:

   • Bell icon in header shows unread count
   • Click to see notification list
   • Click notification to view details
   • Automatically marked as read

3. Email Notifications:

   • Receive formatted HTML emails
   • Click links to view details
   • Manage preferences in profile

For Developers

1. Automatic Triggers:

   // Report created → notifications sent
   await reportService.createReport(data);
   // Automatically triggers notificationService.notifyNewReport()
   
   // Event created → notifications sent
   await eventService.createEvent(data);
   // Automatically triggers notificationService.notifyNewEvent()
   

2. Manual Notifications:

   import { notificationService } from './services/notificationService';
   
   await notificationService.createNotification({
     userId: 'user-id',
     type: 'new_report',
     title: 'New Report',
     message: 'A new report was created',
     relatedId: 'report-id',
     relatedType: 'report',
     latitude: 53.3498,
     longitude: -6.2603,
   });
   

3. Scheduled Jobs:

   • Event reminders: Every 10 minutes
   • Cleanup old notifications: Daily at 2 AM

🎯 API Endpoints

All require authentication:

# Get notifications
GET /api/notifications?unreadOnly=true

# Get unread count
GET /api/notifications/unread-count

# Mark as read
PATCH /api/notifications/:id/read

# Mark all as read
PATCH /api/notifications/read-all

🐛 Troubleshooting

"Forbidden" Error

Problem: Email not authorized in Mailgun sandbox

Solution:

1. Add email to authorized recipients
2. Confirm authorization email
3. Wait 2-3 minutes
4. Try again

Notifications Not Appearing

Problem: User has no areas of interest

Solution:

1. Go to Profile → Notification Settings
2. Add at least one area of interest
3. Create a report/event in that area
4. Check notification bell

Emails Going to Spam

Problem: Sandbox domain has low reputation

Solution:

1. Check spam folder
2. Mark as "Not Spam"
3. For production, use custom domain

📚 Full Documentation

• Implementation Guide: NOTIFICATION_SYSTEM_IMPLEMENTATION.md
• Mailgun Setup: MAILGUN_SETUP.md
• Task Summary: TASK_33_NOTIFICATION_SYSTEM_COMPLETE.md

✅ Checklist

• Authorized email in Mailgun dashboard
• Confirmed authorization email
• Ran test email script successfully
• Ran full notification test successfully
• Checked inbox for test emails
• Tested notification bell in UI
• Set up areas of interest for test user
• Created test report/event
• Verified notification received

🎉 You're Done!

The notification system is ready to use. Users will now receive notifications about reports and events in their areas of interest!

For production deployment, see MAILGUN_SETUP.md for custom domain setup.