Email Queue REST API
A single endpoint for polling the status of an email job group. Used by the Migration Wizard status panel and the Broadcasts admin screen to show real-time delivery progress.
GET /benecaster/v1/shows/{id}/email-queue-status
Returns the current delivery status for a job group — a set of email queue rows identified by a shared related_id and type.
Auth: manage_options + X-WP-Nonce
Parameters:
| Param | Source | Type | Required | Description |
|---|---|---|---|---|
{id} |
Path | int | Yes | Show ID |
related_id |
Query | int | Yes | ID of the entity driving this job group (e.g. migration import ID or broadcast ID) |
type |
Query | string | Yes | Email type string identifying the job group (e.g. migration_invitation, broadcast) |
Response:
{
"total": 89,
"sent": 71,
"failed": 2,
"pending": 16,
"status": "sending",
"estimated_completion": "2026-05-17T15:42:00"
}
Response fields:
| Field | Type | Description |
|---|---|---|
total |
int | Total rows in this job group |
sent |
int | Rows with status sent |
failed |
int | Rows with status failed |
pending |
int | Rows with status pending or in_progress |
status |
string | queued, sending, complete, or complete_with_failures |
estimated_completion |
string|null | ISO 8601 datetime estimated from current pending count and the emails_per_hour setting; null when pending = 0 |
Status values:
| Status | Meaning |
|---|---|
queued |
Job exists but processing hasn’t started yet |
sending |
At least one row sent; rows still pending |
complete |
All rows terminal (sent or failed); zero failures |
complete_with_failures |
All rows terminal; one or more failed rows |
Errors:
| Code | HTTP | Condition |
|---|---|---|
show_not_found |
404 | Show ID does not exist |
invalid_param |
400 | related_id or type missing |
Polling pattern:
The Broadcasts screen polls this endpoint every 30 seconds while status is queued or sending. Stop polling when status is complete or complete_with_failures. The estimated_completion field gives the UI a target to display — it is recalculated on every poll as the pending count decreases.
Relationship to broadcasts:
For broadcasts specifically, use related_id = the broadcast ID and type = broadcast. The GET /broadcasts/{id}/recipients endpoint gives per-recipient detail; this endpoint gives the aggregate counts needed for a status bar.