Send a Benecaster email type from add-on code

Free Beginner

Registering a type with benecaster_managed_email_types makes it discoverable and editable in the Email Editor. It does not make it send. To actually dispatch one, call benecaster_send_email().

Always pass show_id in $context when you have one. Unsubscribe enforcement needs both the user and the show — omit the show and a subscriber who opted out of that show still gets the mail.

The Return Value Is a Queue Row, Not a Delivery Result

benecaster_send_email() returns the benecaster_email_queue row ID. The queue sends later, on the benecaster_process_email_queue cron pass, so a non-zero return means accepted for sending rather than sent.

A 0 return is the only signal a filter suppressed the send. Treat it as “do not retry” — the most common cause is an opt-out, which is not an error and must not be retried.

Code

<?php
add_action( 'benecaster_episode_published', function ( int $episode_id, int $show_id ): void {
    foreach ( benecaster_find_audience_user_ids( $show_id, 'paying' ) as $user_id ) {
        $queue_id = benecaster_send_email(
            $user_id,
            'my_episode_notification',
            /* translators: %s: episode title */
            sprintf( __( 'New episode: %s', 'my-addon' ), get_the_title( $episode_id ) ),
            'my-addon/episode-notification',
            [
                'show_id'       => $show_id,
                'episode_title' => get_the_title( $episode_id ),
                'episode_url'   => get_permalink( $episode_id ),
            ]
        );

        // 0 means suppressed or failed — most often an opt-out, which is
        // not an error and must not be retried.
        if ( 0 === $queue_id ) {
            continue;
        }
    }
}, 10, 2 );

View on GitHub →

Hooks Used

benecaster_managed_email_types

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