Skip to main content

benecaster_get_email_log()

Utilities Free
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 →