EmailQueue
\Benecaster\Email\EmailQueue
Benecaster’s outgoing email queue. Bulk sends (a broadcast, a migration invitation run, an add-on’s own job) are queued one row per recipient and sent in the background.
An add-on may call the four methods below and nothing else. They let an add-on show the podcaster who did and did not get one of its own jobs, and retry failures. Queueing mail and the broadcast listing stay internal. Resolve the class from the container Benecaster hands you on benecaster_boot: $container->make( \Benecaster\Email\EmailQueue::class ).
A job is a pair: the related_id the rows were queued with and their exact email_type. Related IDs are only unique within a type, so broadcast 12 and import 12 are different jobs. These methods work for any email type, not only broadcasts. None of them checks capabilities; your own REST route must.
Methods
| Method | Visibility | Since | Description |
|---|---|---|---|
get_job_recipients( int $related_id, string $type, string $status = '', int $page = 1, int $per_page = 50 ): array |
Public | — | One page of a job's per-recipient rows, oldest first. $status narrows the list to pending, sending, sent, failed, or in_progress (pending and sending together); anything else, including the default '', lists every row. Each row has queue_id, user_id, display_name, email, status, attempts, last_error (or null), sent_at (UTC, or null) and created_at (UTC, when the row was queued). Both datetimes are Y-m-d H:i:s strings; render them with wp_date() or get_date_from_gmt(). display_name and email come from the recipient's WordPress account and are '' when the user has been deleted, so render a fallback. |
count_job_recipients( int $related_id, string $type, string $status = '' ): int |
Public | — | The total for paging get_job_recipients(), with the same job and $status rules. 0 means the job has no rows, which is also how you tell an unknown job from an empty page. |
retry_failed( int $related_id, string $type ): int |
Public | — | Puts every failed row of the job back in the queue and returns how many were reset. Scoped by the job pair itself, so it needs no ownership check. |
retry_single( int $queue_id ): bool |
Public | — | Puts one failed row back in the queue; returns true if a row was reset. ⚠⚠ It checks nothing about which job the row belongs to. Retry only a queue_id you found through get_job_recipients() for your own job. Forwarding a raw id from a request lets anyone who can reach your route re-send another job's email. |