aperonight/docs/email-notifications.md

Email Notifications System

This document describes the email notifications system implemented for ApéroNight.

Overview

The email notifications system provides two main types of notifications:

1. Purchase Confirmation Emails - Sent when orders are completed
2. Event Reminder Emails - Sent at scheduled intervals before events

Features

Purchase Confirmation Emails

• Trigger: Automatically sent when an order is marked as paid
• Content: Order details, ticket information, PDF attachments for each ticket
• Template: Supports both single tickets and multi-ticket orders
• Languages: French (can be extended)

Event Reminder Emails

• Schedule: 7 days before, 1 day before, and day of event
• Content: Event details, user's ticket information, venue information
• Recipients: Only users with active tickets for the event
• Smart Content: Different messaging based on time until event

Technical Implementation

Mailer Classes

TicketMailer

• purchase_confirmation_order(order) - For complete orders with multiple tickets
• purchase_confirmation(ticket) - For individual tickets
• event_reminder(user, event, days_before) - For event reminders

Background Jobs

EventReminderJob

• Sends reminder emails to all users with active tickets for a specific event
• Parameters: event_id, days_before
• Error handling: Logs failures but continues processing other users

EventReminderSchedulerJob

• Runs daily to schedule reminder emails
• Automatically finds events starting in 7 days, 1 day, or same day
• Only processes published events
• Configurable via environment variables

Email Templates

Templates are available in both HTML and text formats:

• app/views/ticket_mailer/purchase_confirmation.html.erb
• app/views/ticket_mailer/purchase_confirmation.text.erb
• app/views/ticket_mailer/event_reminder.html.erb
• app/views/ticket_mailer/event_reminder.text.erb

Configuration

Environment Variables

• MAILER_FROM_EMAIL - From address for emails (default: no-reply@aperonight.fr)
• SMTP_* - SMTP configuration for production
• SCHEDULE_REMINDERS - Enable automatic reminder scheduling in non-production

Development Setup

• Uses localhost:1025 for development (MailCatcher recommended)
• Email delivery is configured but won't raise errors in development

Usage

Manual Testing

# Test purchase confirmation
order = Order.last
TicketMailer.purchase_confirmation_order(order).deliver_now

# Test event reminder
user = User.first
event = Event.published.first
TicketMailer.event_reminder(user, event, 7).deliver_now

# Test scheduler job
EventReminderSchedulerJob.perform_now

Integration in Code

Purchase confirmation emails are automatically sent when orders are marked as paid:

order.mark_as_paid! # Automatically sends confirmation email

Event reminders are automatically scheduled via the initializer, but can be manually triggered:

# Schedule reminders for a specific event
EventReminderJob.perform_later(event.id, 7) # 7 days before

Deployment Notes

Production Configuration

1. Configure SMTP settings via environment variables
2. Set MAILER_FROM_EMAIL to your domain
3. Ensure SCHEDULE_REMINDERS=true to enable automatic reminders
4. Configure solid_queue for background job processing

Monitoring

• Check logs for email delivery failures
• Monitor job queue for stuck reminder jobs
• Verify SMTP configuration is working

Customization

• Email templates can be customized in app/views/ticket_mailer/
• Add new reminder intervals by modifying EventReminderSchedulerJob
• Internationalization can be added using Rails I18n

File Structure

app/
├── jobs/
│   ├── event_reminder_job.rb
│   └── event_reminder_scheduler_job.rb
├── mailers/
│   ├── application_mailer.rb
│   └── ticket_mailer.rb
└── views/
    └── ticket_mailer/
        ├── purchase_confirmation.html.erb
        ├── purchase_confirmation.text.erb
        ├── event_reminder.html.erb
        └── event_reminder.text.erb

config/
├── environments/
│   ├── development.rb (SMTP localhost:1025)
│   └── production.rb (ENV-based SMTP)
└── initializers/
    └── event_reminder_scheduler.rb

test/
├── jobs/
│   ├── event_reminder_job_test.rb
│   └── event_reminder_scheduler_job_test.rb
├── mailers/
│   └── ticket_mailer_test.rb
└── integration/
    └── email_notifications_integration_test.rb

Security Considerations

• No sensitive information in email templates
• User data is properly escaped in templates
• QR codes contain only necessary ticket verification data
• Email addresses are validated through Devise