Skip to main content

benecaster_managed_email_types

Filter Free

Filters the array of registered email types available across the plugin. Every type returned by this filter appears as an editable template in the Email Editor add-on’s template manager. Benecaster registers its own types unconditionally at boot; the billing-lifecycle types among them are registered whether or not the built-in membership feature is active. Add-ons register their own types by hooking this filter at plugin boot.

This is mostly a descriptive catalogue. Registering a type does not make an email send, render or route: sending goes through benecaster_send_email(), and every call site supplies its own subject and template. Registering is what makes the type editable and discoverable. The one exception is 'unsubscribable' => false, below, which changes whether an opted-out subscriber still receives the email.

Each type definition is an associative array with four required keys: type (a stable snake_case identifier unique across all plugins), label (human-readable name shown in the Email Editor), description (one-sentence summary of when the email is sent), and add_on (the registering add-on’s slug, or null for Benecaster types). The type string becomes part of type-specific hook names — keep it stable after release.

Three optional keys:

  • unsubscribable — set to false and the email is delivered even to a subscriber who has opted out of all email. Absent means the email can be suppressed. Reserve it for mail a person cannot do without, such as a link back into their own account. Adding a type to benecaster_transactional_email_types only protects it from a broadcast opt-out; see Customizing Emails.

  • send_reason — why the email is sent, for example account_provisioning. Descriptive only.

  • default_template_path — the name of the template the email renders from, exactly as a send passes it (for example feed-link, not a file path). It is looked up the same way a send’s template is, so it finds a Benecaster template, a theme’s override of it, or an add-on’s own. Descriptive only; the sender still passes its own template.

Parameters

Name Type Default Description
$types array — Ordered array of type definition arrays: {type: string, label: string, description: string, add_on: string|null}

Returns: array

Examples

Register weekly digest email type

add_filter( 'benecaster_managed_email_types', function( $types ) {
    // Register a custom "weekly_digest" email type for an add-on.
    $types[] = [
        'type'        => 'weekly_digest',
        'label'       => 'Weekly Digest',
        'description' => 'A curated weekly roundup sent every Monday.',
        'add_on'      => 'my-digest-addon',
    ];
    return $types;
} );

Register type at plugin boot

add_action( 'benecaster_boot', function ( \Benecaster\Container $container ): void {
    add_filter( 'benecaster_managed_email_types', function ( array $types ): array {
        $types[] = [
            'type'        => 'my_episode_notification',
            'label'       => __( 'Episode Notification', 'my-addon' ),
            'description' => __( 'Sent to subscribers when a new episode becomes available for their tier.', 'my-addon' ),
            'add_on'      => 'my-addon',
        ];
        return $types;
    } );
} );

Notes

Register this filter at benecaster_boot, not init. The filter is read during plugin boot — registering on init or later may mean your type is absent when the Email Editor queries the list.

Do not reuse a type string Benecaster already registers, and read the list at runtime rather than from any page. apply_filters( 'benecaster_managed_email_types', [] ) returns Benecaster's types plus every active add-on's, which is the only answer that stays correct as either changes. A hand-copied list would go stale, and a collision is silent. There is no token_revoked email type — benecaster_token_revoked is an action that fires when a feed token is revoked, and the two are unrelated.

Related Recipes

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