Broadcasts REST API

Endpoints for monitoring and managing email broadcasts. Broadcasts are bulk email sends to a show’s subscriber list (or a filtered subset). No premium license is required to use these endpoints.

All endpoints require manage_options and a valid X-WP-Nonce header.

---

GET /benecaster/v1/broadcasts

Returns a paginated list of broadcast records for a show.

Auth: manage_options + X-WP-Nonce

Parameters:

Response:

{
  "items": [
    {
      "id": 12,
      "show_id": 45,
      "subject": "New episode: Season finale is here",
      "created_at": "2026-05-17 09:00:00",
      "total": 247,
      "sent": 245,
      "failed": 2,
      "pending": 0,
      "status": "complete_with_failures"
    }
  ],
  "total": 8
}

Newest first. The response is items and total only. pending counts recipients still queued or being sent. created_at is when the broadcast was queued, as a UTC Y-m-d H:i:s string with no zone marker; treat it as UTC before parsing, the same as sent_at below.

Status values:

There is no status filter: the status is worked out from each broadcast’s counts.

The Broadcasts admin screen polls this endpoint every 30 seconds while any broadcast has status queued or sending.

---

GET /benecaster/v1/broadcasts/{id}/recipients

Returns per-recipient delivery status for a broadcast.

Auth: manage_options + X-WP-Nonce

Parameters:

Response:

{
  "items": [
    {
      "queue_id": 4821,
      "user_id": 112,
      "display_name": "Sarah Chen",
      "email": "sarah@example.com",
      "status": "sent",
      "attempts": 1,
      "last_error": null,
      "sent_at": "2026-05-17 09:03:00",
      "created_at": "2026-05-17 09:00:00"
    },
    {
      "queue_id": 4822,
      "user_id": 113,
      "display_name": "Bob Martinez",
      "email": "bob@example.com",
      "status": "failed",
      "attempts": 3,
      "last_error": "SMTP connection timeout",
      "sent_at": null,
      "created_at": "2026-05-17 09:00:00"
    }
  ],
  "total": 247
}

The response is items and total only. Work out the page count from total and the per_page you asked for. Rows come oldest first.

sent_at and created_at are UTC, with no zone marker. Both are Y-m-d H:i:s strings; sent_at is null until that recipient has been sent, and created_at is when they were queued. Treat them as UTC before parsing: for example, replace the space with T and append Z. Parsed as they stand, most JavaScript runtimes read them as the viewer’s local time and show the wrong hour.

display_name and email are read from the recipient’s WordPress account, and are empty strings for a recipient whose account has since been deleted.

Recipient status values:

---

POST /benecaster/v1/broadcasts/{id}/retry-all

Resets all failed recipient rows in a broadcast to pending, re-queuing them for delivery. Recipients that already succeeded are unaffected.

Auth: manage_options + X-WP-Nonce

Response:

{
  "requeued": 2,
  "broadcast_status": "sending"
}

requeued is the count of rows that moved from failed back to pending. If there are no failed rows, requeued is 0 and broadcast_status reflects the current status.

Errors:

---

POST /benecaster/v1/broadcasts/{id}/recipients/{qid}/retry

Resets a single failed recipient row to pending, re-queuing it for delivery. {qid} is the recipient row ID from GET /broadcasts/{id}/recipients.

Auth: manage_options + X-WP-Nonce

Response:

{
  "requeued": true
}

Errors:

---

Recipe

Recipe: Query Broadcast Delivery Status from an External Tool — use GET /broadcasts and GET /broadcasts/{id}/recipients from an external script or CI pipeline to monitor delivery after a scheduled send.