Register a custom email type with the Email Editor

Any email type registered via benecaster_managed_email_types appears as an editable template in the Email Editor UI. Add-ons that send their own email types — episode notifications, community alerts, digest emails — should register them here so podcasters can customize the templates without code. Core registers its own types through this same filter.

Check what core already occupies before you choose a type string, and check it at runtime rather than against a list on a page. apply_filters( 'benecaster_managed_email_types', [] ) returns everything registered — core plus every active add-on — which is the only answer that stays correct as either changes. A name that collides with a type already registered is the failure this avoids, and the collision is silent.

When to Use This

Register a custom email type when your add-on sends transactional emails through Benecaster and you want podcasters to be able to customize the template via the Email Editor add-on. Examples: an episode notification email, a grace-period warning email, a community welcome email sent when a subscriber connects Discord.

If your add-on sends one-off utility emails that shouldn’t be user-customizable, you can call wp_mail() directly without registering a type.

Step 1 — Register the Type

Filter benecaster_managed_email_types from inside a benecaster_boot callback, so the type exists by the time the Email Editor queries the list. Each entry carries a type string, a label, a description, and the add_on slug. Once registered, the type appears in the Email Editor’s template manager as an editable template.

Step 2 — Dispatch the Email

Registering the type does not send it. Call benecaster_send_email():

$queue_id = benecaster_send_email(
    $user_id,
    'my_addon_delivery_email',
    __( 'Your delivery is on its way', 'my-addon' ),
    'my-addon/delivery-notice',
    [ 'show_id' => $show_id ]
);

This routes the message through the queue, applies every registered filter (benecaster_email_subject, benecaster_email_body_html, and the rest), and respects unsubscribe preferences — which is exactly what calling wp_mail() directly would bypass.

The context array becomes additional merge tag data. Pass show_id in it whenever you have one: unsubscribe enforcement needs both the user and the show, and without the show a subscriber who opted out of that show still receives the mail.

The return value is a queue row ID, not a delivery result. A 0 means a filter suppressed the send, most often an opt-out — treat it as do not retry.

Worked example: Send a Benecaster email type from add-on code. For one-off mail with no registered type behind it, use benecaster_mail().

Step 3 — Add Merge Tags (Optional)

Type-specific merge tags come from the filter benecaster_email_merge_tags_{$type}, where {$type} is the string you registered. Your callback receives the existing tag array, the user ID, and the show ID; read anything you passed as context from $tags['context'], then add your own {{tag}} keys and return the array.

Step 4 — Suppress for Unsubscribed Users (Optional)

There’s a matching per-type variant of the suppression filter: benecaster_email_should_send_{$type}. Return false to suppress — typically after checking a per-user opt-out your add-on stores in user meta — and otherwise return the incoming value unchanged so other callbacks keep their say.

Notes

Type string stability. The type string you register becomes part of all the type-specific filter tags. Renaming it after launch breaks any customizations podcasters have applied in the Email Editor. Choose it carefully and keep it stable.

The add_on field. Set this to your add-on’s slug. The Email Editor uses it to group templates by add-on and to show a “Requires: My Add-on” badge on the entry.

Benecaster types are protected. Do not use welcome, token_reset, or token_revoked as your type string — these are registered by Benecaster and always present.

Related

• Default Email Templates — how the Benecaster email pipeline works