Customizing Email Templates with PHP

This walkthrough covers the three ways to change what Benecaster’s emails say and how they look, from least to most invasive. Work down the list and stop at the first one that does what you need — each step costs more maintenance than the one before it.

You’ll need to be comfortable adding PHP to a site. Put the code in a child theme’s functions.php or, better, a small site-specific plugin, so a theme update can’t remove it.

Before You Start

If you have the Email Editor add-on, you don’t need any of this. It provides a visual editor for all of it. This tutorial is for people working without it.

Test on staging if you have one. A PHP error in email code can break sending silently — the queue keeps accepting messages, and nothing goes out.

1. Change Branding Without Touching Templates

Most branding changes need no template work at all. The wrapper that surrounds every email — logo, accent color, footer text — comes from a filterable array.

add_filter( 'benecaster_email_wrapper_args', function( array $args ): array {
    $args['logo_url']     = 'https://example.com/wp-content/uploads/logo.png';
    $args['accent_color'] = '#1a5f7a';
    $args['footer_text']  = 'The Example Show — thanks for listening.';
    return $args;
} );

That’s the whole job for a typical rebrand. No files copied, nothing to maintain against future updates.

Admin emails pass is_admin_email as true and omit the unsubscribe link. Check that key if you want different branding for admin mail:

add_filter( 'benecaster_email_wrapper_args', function( array $args ): array {
    if ( ! empty( $args['is_admin_email'] ) ) {
        return $args;   // leave admin emails with default styling
    }
    $args['accent_color'] = '#1a5f7a';
    return $args;
} );

2. Change Wording Without Touching Templates

Subject lines and body copy are filterable per email type. The type-specific variant — the email type appended to the filter name — is the one to use when you’re targeting a single email.

add_filter( 'benecaster_email_subject_welcome', function( string $subject ): string {
    return 'Your private feed is ready';
} );

Merge tags work the same way, which lets you add your own without editing a template:

add_filter( 'benecaster_email_merge_tags_welcome', function( array $tags, $user_id, $show_id ): array {
    $tags['{{support_email}}'] = 'help@example.com';
    return $tags;
}, 10, 3 );

Then use {{support_email}} in the template. See Email Merge Tags for what’s already available before you add anything.

3. Override a Template File

When you need different markup — not just different colors or words — copy the template into your theme.

Override path:

{your-theme}/benecaster/emails/{template}.php

Benecaster checks the child theme first, then the parent theme, then falls back to its own copy. So to change the welcome email body, copy Benecaster’s templates/emails/welcome.php to your-theme/benecaster/emails/welcome.php and edit the copy.

Each body template has variables available to it — $feed_url and $tier_name in the welcome email, for example. Customizing Emails lists the variables for every template, along with the full file list.

The header and footer are not separate files. They’re rendered inside base.php. To restructure them you override base.php itself — but for color, logo, or footer text, use the benecaster_email_wrapper_args filter from step 1 instead, which doesn’t leave you maintaining a copy of the wrapper.

The Maintenance Cost of Overrides

An overridden template is frozen at the moment you copied it. If a later Benecaster release fixes a rendering bug in welcome.php, or adds a new variable, your copy won’t get it — your site keeps using the old version indefinitely, with no warning.

That’s the reason for the ordering in this tutorial. Filters survive updates; copied templates don’t. Override a file only when a filter genuinely can’t do the job, and keep a note of which files you’ve overridden so you can compare them after a major release.

Testing Your Changes

There’s no built-in test send without the Email Editor add-on, so trigger the real thing on a staging site:

• Welcome email — add a subscriber manually from Benecaster → Subscribers
• Token reset — reset your own test subscriber’s token
• Tier change — change that subscriber’s tier

Watch the queue depth in Benecaster → Settings → Email to confirm the message was actually queued. If nothing queues after a code change, you likely have a PHP error — check your site’s error log.