benecaster_get_email_log()
benecaster_get_email_log( array $args = [] ): array
Reads Benecaster’s email log: one row per email it was asked to send, with what became of it. Use it to show a podcaster which emails went out, which failed and why, and to find the log id that benecaster_resend_email() and benecaster_forward_email_to_admin() take.
status is one of: queued (in the queue, not yet handed over); held (queued on a copy of the site, which sends nothing but test sends until it is declared production); expired (held for more than three days and dropped unsent, the reason in error_message); sent (handed to wp_mail(), which is as far as Benecaster can see); failed; suppressed (refused by an opt-out or a filter, the reason in error_message); or test. On a copy of the site, a test send is the one email that still goes out.
Parameters
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
args |
array |
[] |
No | Optional filters, combined with AND; leave a key out to mean "any". email_type — a type or a list of types. show_id (0 for email that belongs to no show) and user_id. date_from / date_to — UTC and inclusive, as Y-m-d (the whole day) or Y-m-d H:i:s. limit — default 50, at most 500. offset — rows to skip. |
Return Value
Type:
array
One row per email Benecaster was asked to send, newest first: id, sent_at (UTC, Y-m-d H:i:s), email_type, recipient_email, subject, status, user_id, show_id, queue_id (the queue row holding the body that went out) and error_message. The last four may be null. An empty array when nothing matches or a filter is malformed.
Example
if ( current_user_can( 'manage_options' ) ) {
$rows = benecaster_get_email_log( [
'show_id' => $show_id,
'email_type' => [ 'welcome', 'payment_failed' ],
'date_from' => gmdate( 'Y-m-d', strtotime( '-7 days' ) ),
] );
foreach ( $rows as $row ) {
printf(
'<li>%s — %s — %s</li>',
esc_html( wp_date( 'j M Y H:i', strtotime( $row['sent_at'] . ' UTC' ) ) ),
esc_html( $row['recipient_email'] ),
esc_html( $row['status'] )
);
}
}
Notes
There is no capability check, and rows carry email addresses. Check manage_options, or your own capability, before showing them.
show_id => 0 means email that belongs to no show, never "any show": account email such as address verification and setting a password. Such a row comes back with show_id null. That mail is install-wide, so list it only on a screen that is itself install-wide, never under one show. See List the account emails that belong to no show.
A malformed filter returns an empty array and raises a _doing_it_wrong() notice, never every row: a negative show id, a user id below 1, an empty type list, or a date in any other form.
There is no status filter; filter the rows yourself. sent_at is the time the email was queued for every status except sent, where it is the hand-off to wp_mail(), and a date range filters on it as stored. It is UTC: convert it with wp_date() for display.
Rows are kept only for benecaster_get_email_log_retention_days(). A failed row written before the log recorded a user and show names neither, so a user filter or a show id of 1 or more misses it, and show_id => 0 finds it. For paging, benecaster_count_email_log() takes the same filters. See List a show's failed emails.
Need this built rather than just documented? See our services →