feat: complete email infrastructure with queue, templates, logging, and API
Adds the full transactional email system:
- Redis queue (QUEUE_CONNECTION=redis), SES config in .env.example
- 3 migrations: organisation_email_settings, organisation_email_templates, email_logs
- EmailTemplateType and EmailLogStatus enums with Dutch defaults
- EmailService as central entry point for all email sending
- SendTransactionalEmail queued job with retries and idempotency
- TransactionalMail mailable with responsive HTML + plain text templates
- Organisation-level branding (colors, logo, footer, reply-to)
- Per-type template overrides with {variable} substitution
- Email log with filtering by status, type, date range, recipient
- Preview and send-test endpoints for template management
- API endpoints: email-settings, email-templates (CRUD), email-logs (read-only)
- Integrated into existing flows: invitations, password reset, email
verification, registration approval/rejection
- 37 new tests across 4 test files, all existing tests updated
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
118
dev-docs/API.md
118
dev-docs/API.md
@@ -922,3 +922,121 @@ Base path: `/api/v1/admin/`
|
||||
- Impersonation token has name `impersonation-by-{admin_id}`
|
||||
- Admin ID is cached for 4 hours at key `impersonation:{token_id}`
|
||||
- Activity log records both start (`admin.impersonation.started`) and stop (`admin.impersonation.stopped`)
|
||||
|
||||
## Email Settings (org admin)
|
||||
|
||||
- `GET /organisations/{org}/email-settings` — get current email branding settings (returns defaults if none configured)
|
||||
- `PUT /organisations/{org}/email-settings` — create or update email branding settings
|
||||
|
||||
### PUT body
|
||||
|
||||
```json
|
||||
{
|
||||
"logo_url": "https://example.com/logo.png",
|
||||
"primary_color": "#FF5500",
|
||||
"secondary_color": "#CC4400",
|
||||
"footer_text": "© 2026 Stichting Feestfabriek",
|
||||
"reply_to_email": "info@festival.nl",
|
||||
"reply_to_name": "Festival Team"
|
||||
}
|
||||
```
|
||||
|
||||
All fields are optional/nullable. Colors must match `#[0-9A-Fa-f]{6}`.
|
||||
|
||||
## Email Templates (org admin)
|
||||
|
||||
- `GET /organisations/{org}/email-templates` — list all template types with current content (custom or default)
|
||||
- `GET /organisations/{org}/email-templates/{type}` — get single template with both custom content and defaults
|
||||
- `PUT /organisations/{org}/email-templates/{type}` — create or update custom template for this type
|
||||
- `DELETE /organisations/{org}/email-templates/{type}` — reset to system default (deletes custom override)
|
||||
- `POST /organisations/{org}/email-templates/{type}/preview` — render email HTML with sample data
|
||||
- `POST /organisations/{org}/email-templates/{type}/send-test` — send test email. Body: `{ "email": "test@example.com" }`
|
||||
|
||||
### Template types
|
||||
|
||||
`invitation`, `password_reset`, `email_verification`, `registration_approved`, `registration_rejected`, `shift_assignment`
|
||||
|
||||
### PUT body
|
||||
|
||||
```json
|
||||
{
|
||||
"subject": "Aangepaste uitnodiging voor {organisation_name}",
|
||||
"heading": "Welkom!",
|
||||
"body_text": "Aangepaste tekst met {organisation_name} variabelen.",
|
||||
"button_text": "Klik hier"
|
||||
}
|
||||
```
|
||||
|
||||
### GET response (index)
|
||||
|
||||
Returns array of all template types with resolved content:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"type": "invitation",
|
||||
"label": "Uitnodiging",
|
||||
"is_custom": false,
|
||||
"subject": "Je bent uitgenodigd voor {organisation_name}",
|
||||
"heading": "Welkom bij {organisation_name}!",
|
||||
"body_text": "...",
|
||||
"button_text": "Uitnodiging accepteren",
|
||||
"defaults": { "subject": "...", "heading": "...", "body_text": "...", "button_text": "..." }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Template variables
|
||||
|
||||
- `{organisation_name}` — available in all templates
|
||||
- `{event_name}` — available in registration and shift templates
|
||||
- `{shift_title}`, `{shift_date}`, `{shift_start}`, `{shift_end}`, `{section_name}` — shift assignment only
|
||||
|
||||
## Email Logs (org admin, read-only)
|
||||
|
||||
- `GET /organisations/{org}/email-logs` — paginated email log
|
||||
|
||||
### Query parameters
|
||||
|
||||
| Param | Type | Description |
|
||||
| --------------- | ------ | ------------------------------------ |
|
||||
| `search` | string | Search by recipient_email |
|
||||
| `status` | string | Filter: `queued\|sent\|failed` |
|
||||
| `template_type` | string | Filter by EmailTemplateType |
|
||||
| `event_id` | ULID | Filter by event |
|
||||
| `person_id` | ULID | Filter by person |
|
||||
| `from` | date | Start of date range |
|
||||
| `to` | date | End of date range |
|
||||
| `per_page` | int | Results per page (default 15) |
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"data": [
|
||||
{
|
||||
"id": "01JXYZ...",
|
||||
"recipient_email": "volunteer@test.nl",
|
||||
"recipient_name": "Jan Janssen",
|
||||
"template_type": "registration_approved",
|
||||
"template_label": "Registratie goedgekeurd",
|
||||
"subject": "Je registratie voor Festival X is goedgekeurd!",
|
||||
"status": "sent",
|
||||
"error_message": null,
|
||||
"queued_at": "2026-04-15T12:00:00+00:00",
|
||||
"sent_at": "2026-04-15T12:00:05+00:00",
|
||||
"failed_at": null,
|
||||
"triggered_by": { "id": "01JXYZ...", "name": "Admin User" },
|
||||
"event_id": "01JXYZ...",
|
||||
"person_id": "01JXYZ...",
|
||||
"created_at": "2026-04-15T12:00:00+00:00"
|
||||
}
|
||||
],
|
||||
"links": { "...pagination..." },
|
||||
"meta": { "...pagination..." }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user