Skip to main content

benecaster_email_template_body

Filter Free

Supplies an email’s body from stored content instead of its template file. Return an HTML string and Benecaster uses it as the body; return null, the default, and the type’s template renders as usual. This is how an email editor sends a design the podcaster made, per show, without a theme file.

The body you return is still wrapped: the header, footer, unsubscribe link and the show’s business address are added exactly as they are for a template’s output.

Put {{tag}} placeholders in the HTML, not values. Benecaster fills them in from $tags and escapes each one by its kind in the merge-tag catalogue (benecaster_email_merge_tag_catalog): a text tag is escaped as text, a URL tag as a URL, and only a tag declared as HTML passes through as HTML. A value you substitute yourself is not escaped.

Parameters

Name Type Default Description
$html string|null — `null`, so the template renders. For a send that carries its own body, such as a broadcast, it is that body
$email_type string — Email type string
$tags array — The resolved merge tags, keyed by tag name without braces; values unescaped
$show_id int|null — ID of the show; null for an email sent outside any show
$user_id int|null — WordPress user ID of the recipient; null when the email is not sent to an account

Returns: string|null

Example

add_filter( 'benecaster_email_template_body', function ( ?string $html, string $email_type, array $tags, ?int $show_id ): ?string {
    if ( 'welcome' !== $email_type || null === $show_id || ! benecaster_addon_is_active( 'my-addon', $show_id ) ) {
        return $html;
    }
    $stored = (string) get_post_meta( $show_id, '_my_addon_welcome_html', true );

    // Placeholders such as {{subscriber_name}}, not values: Benecaster fills them in and escapes them.
    return '' !== $stored ? $stored : $html;
}, 10, 4 );

Notes

Stored content beats a theme override. A non-null return is used even when the active theme ships its own template for that email. The theme's override still applies to every email you return nothing for, so return content only for a show that actually has some.

Return what you were given for a broadcast. When the send carries its own body, $html arrives as that body rather than null, and replacing it replaces the message the podcaster wrote.

It fires for emails with no show, with $show_id null: email-address verification, a donor's data-erasure confirmation, and a set-password email sent outside a show. benecaster_addon_is_active() needs a show, so gate those on benecaster_addon_is_active_for_any_show(). That is safe here because this decides how an email looks, not who may read something.

Previews and test sends run it too, so a preview shows the design that will be sent.

The outer shell is replaced the same way through benecaster_email_template_wrapper. Full walkthrough: Send your own design for one Benecaster email, per show.

Affects

  • The body of every Benecaster email

Related Recipes

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