Your IP : 216.73.217.79

Current Path : /var/git/cesa-v3/docs/specs/
Upload File :
Current File : /var/git/cesa-v3/docs/specs/mail-queue-monitor-requirements.md

# Mail queue monitor — requirements

**System:** cesa-v3  
**Status:** Approved for implementation  
**Related:** cesa-mail bulk send (`Messages`, `ToSend` tables)

## Background

Bulk e-mail from list aliases (cesa-mail) and cesa-main is queued in a separate mail database. Operations staff need visibility into the queue without direct database access.

## User stories

### US-1: View campaign queue

As an authenticated CESA admin, I want a page listing bulk-mail campaigns (`Messages`) so I can see what is in the queue and whether each campaign has finished.

### US-2: Per-campaign send counts

For each campaign, I want to see how many recipient rows (`ToSend`) are **pending**, **sent**, and **failed**, so I can judge progress and problems at a glance.

### US-3: Drill into a campaign

As an admin, I want to open a campaign and see its metadata and per-recipient rows (recipient, status) so I can investigate stuck or failed sends.

### US-4: Queue summary

On the list page, I want summary totals (campaigns still sending, total pending/sent/failed recipient rows) so I can assess overall mail-system health quickly.

## Acceptance criteria

1. Page is available only to users with `ROLE_ADMIN` or `ROLE_MAIL_QUEUE_ADMIN`.
2. Data is read from the mail database (`Messages`, `ToSend`); no writes from this feature.
3. **Pending** = `ToSend.Sent = 0`; **sent** = `1`; **failed** = `2` (legacy cesa-main / `ToSendProcess.php` semantics).
4. List shows at least: Message ID, subject, sent-to group, date sent, send complete flag, pending/sent/failed counts, link to detail.
5. Detail shows message fields and a paginated table of `ToSend` rows with status labels.
6. If the mail database is unreachable, the user sees a clear error message (no stack trace in production).
7. Feature is documented in design spec and mail data model spec (cesa-mail).

## Out of scope

- Requeue, cancel, or edit messages.
- School-only mail paths beyond read-only display (`FromSchool` may be shown but not filtered unless requested later).
- cesa-mail PHP repo changes (ingress unchanged).