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

```ruby
# 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:

```ruby
order.mark_as_paid! # Automatically sends confirmation email
```

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

```ruby
# 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