Skip to main content

benecaster_marketing_consent_changed

Action Free

Fires after a person’s marketing-consent answer for a show is recorded and something changed: a first answer, a different answer, or an unverified answer becoming verified. Benecaster asks for consent only when an add-on asks it to, through benecaster_marketing_consent_label, and never sends marketing email itself; this hook is how the add-on hears the answer.

Answers come from four places, named by $source: subscribe (a paid tier on the [benecaster_subscribe] checkout), free_tier_signup (a free tier on that checkout), follower_signup ([benecaster_follower_signup]) and donation (the donation form’s own Add me to this show’s mailing list box, which records a yes whether or not an add-on asks). A checkout’s answer is recorded only once the membership is created — at once for a free tier, after the card or a 3D Secure check succeeds for a paid one.

$verified is whether the address was proven to belong to the person answering. The follower form and a guest checkout take an address anyone can type, so an answer from an unproven address arrives with $verified false. It becomes true, and this hook fires again, when the address owner answers while logged in or clicks a marketing button in an email that states the answer: Confirm and follow, and yes to: in the follower confirmation email, or Yes to: in the Welcome email of a logged-out free-tier signup. Confirm and follow on its own does not verify it. An unverified answer never replaces a verified one, and a logged-out follower submission never replaces an answer from subscribe or donation. A cautious add-on emails only when $granted && $verified.

It does not fire for a re-submitted identical answer, nor for an unverified answer refused because a verified one exists. To read the current answer at any time, call benecaster_get_marketing_consent().

Parameters

Name Type Default Description
$user_id int — WordPress user ID of the person who answered
$show_id int — ID of the show the answer is for
$granted bool — `true` when the box was ticked, `false` when it was shown and left unticked
$source string — `subscribe`, `free_tier_signup`, `follower_signup` or `donation`
$verified bool — Whether the address was proven to belong to the person answering

Examples

Queue a subscribe or unsubscribe in your email platform

add_action( 'benecaster_marketing_consent_changed', function ( int $user_id, int $show_id, bool $granted, string $source, bool $verified ): void {
    if ( $granted && $verified ) {
        my_esp_subscribe_later( $user_id, $show_id ); // e.g. Action Scheduler
    } elseif ( ! $granted ) {
        my_esp_unsubscribe_later( $user_id, $show_id );
    }
}, 10, 5 );

Notes

Queue any API call; never make it inline. This fires inside a form submission, a checkout or a Stripe webhook. Worked example: the recipe Ask for marketing consent on Benecaster's own forms.

Related Recipes

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