Skip to main content

benecaster_email_template_wrapper

Filter Free

Supplies an email’s wrapper, the shell around every body, from stored content instead of Benecaster’s built-in one. Return a complete HTML document; return null, the default, and the built-in wrapper renders as usual.

The document can carry these placeholders:

  • {{body}}: required. Where the email’s body goes. A wrapper without it is ignored and the built-in wrapper
    is used, so a design can never send an empty shell.
  • {{preheader}}: the inbox preview text, escaped.
  • {{business_address}}: the show’s postal address, escaped, with its line breaks kept.
  • any merge tag, escaped by its kind in the merge-tag catalogue, as for
    benecaster_email_template_body.

Parameters

Name Type Default Description
$html string|null — `null`, so the built-in wrapper renders
$email_type string — Email type string
$wrapper_args array — The wrapper context after [benecaster_email_wrapper_args](/hooks/benecaster_email_wrapper_args/): logo_url, show_name, accent_color, footer_text, business_address, preheader
$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_wrapper', function ( ?string $html, string $email_type, array $wrapper_args, array $tags, ?int $show_id ): ?string {
    if ( null === $show_id || ! benecaster_addon_is_active( 'my-addon', $show_id ) ) {
        return $html;
    }
    $stored = (string) get_post_meta( $show_id, '_my_addon_wrapper_html', true );

    // Must contain {{body}}, or Benecaster ignores it and uses its own wrapper.
    return str_contains( $stored, '{{body}}' ) ? $stored : $html;
}, 10, 5 );

Notes

The business address cannot be designed out. When the show has a business address and your wrapper has no {{business_address}}, Benecaster adds it at the end of the document, because it is the legal requirement the footer exists to carry.

The preview text is not padded for you here. Benecaster's built-in wrapper follows the preview text with invisible filler so the body's first words do not trail after it in the inbox; {{preheader}} is the text alone.

Stored content beats a theme override, and the filter fires for emails with no show, exactly as benecaster_email_template_body does — see that page for how to gate those.

Affects

  • The wrapper (header and footer) of every Benecaster email

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