Email Queue REST API

A single endpoint for polling the status of an email job group. Used by the Migration Wizard status panel, the Broadcasts admin screen and Benecaster’s admin sending banner to show real-time delivery progress. An add-on can put its own job in that banner; see Showing Your Job in the Admin Banner.

---

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:

Response:

{
  "total": 89,
  "sent": 71,
  "failed": 2,
  "pending": 16,
  "status": "sending",
  "estimated_completion": "2026-05-17T15:42:00"
}

Response fields:

Status values:

Errors:

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.

---

Showing Your Job in the Admin Banner

Benecaster’s admin shows a sending banner at the top of every Benecaster screen — “Sending {label}: 47 of 1,203 sent” with a View status → link — for one email job at a time. It follows the job named in the browser’s localStorage under the key benecaster_active_email_job, and polls this endpoint for it. It re-reads the key whenever the podcaster moves to another Benecaster screen, and when another tab writes it, so the banner appears as soon as your job starts.

The banner does not discover jobs from the server. No key, no banner: an add-on that queues email and wants the banner writes the key itself.

localStorage.setItem( 'benecaster_active_email_job', JSON.stringify( {
    show_id:    showId,              // the show the queue rows belong to
    related_id: importId,            // the queue rows' related_id
    type:       'migration_welcome', // the rows' exact email_type: the banner polls with it
    label:      __( 'welcome emails', 'my-addon' ), // lowercase and translated
    view_url:   statusPageUrl,       // optional: adds the View status link
} ) );

• Only one job is followed. The broadcast screen writes the same key while a broadcast sends, so the last writer wins.
• The banner clears the key when the podcaster dismisses its completion notice. If your job ends another way, clear it yourself with localStorage.removeItem( 'benecaster_active_email_job' ).
• The key name and the field names are a stable contract for add-ons.