Skip to main content

benecaster_email_suppressed

Action Free

Fires when benecaster_email_should_send (or its _{type} variant) refuses a send. Nothing is rendered or queued, and none of the before- or after-send actions fire. Benecaster’s email log records a suppressed row with the reason, so the person’s data export shows the email they were not sent.

$reason is opted_out_all, opted_out_broadcast or opted_out_episode_notifications when the recipient’s own opt-out is why. Anything else that refused the send reads filtered: the gate is a yes/no filter, so a refusal by another plugin, or by Benecaster holding back the welcome email when the site owner signs up as their own follower, cannot say why. There is no filter to name a custom reason.

A filtered row is not a deliverability problem. It often means another component deliberately sent its own email instead. The Migration Wizard does this for every imported person, replacing the standard welcome with its own, so a large migration leaves one filtered welcome per person in the log. Only the opted_out_* reasons say the recipient asked not to hear from you.

$subject has its merge tags replaced from the global tags and the caller’s context only. The merge-tag filters do not run, because a refused send does no rendering work.

Parameters

Name Type Default Description
$email_type string — Stable email type string (e.g. `broadcast`).
$recipient string — Address the email would have gone to.
$subject string — Subject line, with global and context merge tags replaced.
$user_id int|null — WordPress user ID, or null.
$show_id int|null — Show ID, or null.
$reason string — `opted_out_all`, `opted_out_broadcast`, `opted_out_episode_notifications` or `filtered`.

Examples

Count opt-out suppressions per show

add_action( 'benecaster_email_suppressed', function(
    string $email_type,
    string $recipient,
    string $subject,
    ?int   $user_id,
    ?int   $show_id,
    string $reason
): void {
    if ( 'filtered' === $reason || null === $show_id ) {
        return; // Only the recipient's own opt-outs.
    }
    $key   = 'my_suppressed_' . $show_id;
    $count = (int) get_option( $key, 0 );
    update_option( $key, $count + 1, false );
}, 10, 6 );

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