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",
      "status": "complete",
      "total_recipients": 247,
      "sent": 245,
      "failed": 2,
      "pending": 0,
      "created_at": "2026-05-17T09:00:00",
      "completed_at": "2026-05-17T09:48:00"
    }
  ],
  "total": 8,
  "pages": 1,
  "per_page": 20,
  "page": 1
}

Status values:

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": [
    {
      "id": 4821,
      "email": "sarah@example.com",
      "display_name": "Sarah Chen",
      "status": "sent",
      "sent_at": "2026-05-17T09:03:00",
      "failed_at": null,
      "failure_reason": null,
      "retry_count": 0
    },
    {
      "id": 4822,
      "email": "bob@example.com",
      "display_name": "Bob Martinez",
      "status": "failed",
      "sent_at": null,
      "failed_at": "2026-05-17T09:05:00",
      "failure_reason": "SMTP connection timeout",
      "retry_count": 1
    }
  ],
  "total": 247,
  "pages": 5,
  "per_page": 50,
  "page": 1
}

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.