Skip to main content

benecaster_email_send_failed

Action Free

Fires when Benecaster could not queue an email, so nothing was queued and benecaster_after_email_send does not fire. Two causes: the enqueue itself threw, or the email’s body was empty after the body filters ran — a template that does not exist renders nothing, and Benecaster refuses to send a blank email. Use this hook for logging or alerting.

It does not fire when the queue processor later fails to hand a queued email to wp_mail(); Benecaster’s email log records that as failed after the last of three attempts. Bounces and spam filtering happen after the hand-off and are invisible to Benecaster: for delivery tracking, use an SMTP service with delivery webhooks. The $subject parameter gives you the resolved subject line, which is useful for correlating log entries with specific email sends.

Parameters

Name Type Default Description
$email_type string — Stable email type string (e.g. `welcome`).
$recipient string — Destination address.
$subject string — Subject line, with merge tags already replaced.
$error_message string — Why nothing was queued: the error from the failed enqueue, or a message naming the template that rendered nothing. Not a user ID.

Examples

Alert Slack on failed welcome email

add_action( 'benecaster_email_send_failed', function(
    string $email_type,
    string $recipient,
    string $subject,
    string $error_message
): void {
    if ( $email_type !== 'welcome' ) {
        return;
    }
    wp_remote_post( MY_SLACK_WEBHOOK, [
        'body' => json_encode([
            'text' => sprintf(
                ':warning: Welcome email to %s could not be queued: %s',
                $recipient, $error_message
            ),
        ]),
        'headers' => [ 'Content-Type' => 'application/json' ],
    ] );
}, 10, 4 );

Notes

Covers a failed enqueue only. A queued email that later fails to send shows as failed in the email log, and bounces are never seen by Benecaster.

Need this built rather than just documented? See our services →