Skip to main content

benecaster_email_merge_tag_catalog

Filter Free

Describes every {{tag}} a Benecaster email can carry, so an email editor can list them, offer them as you type and fill a preview with sample data. Each entry is keyed by the tag name without braces and carries:

  • label (string): the tag’s display name.
  • description (string): what the tag holds, and when it is empty.
  • types (array): the email types the tag appears in. An empty array means every email.
  • sample (string): the value a preview or test send uses when there is no real one.
  • kind (string): text, url or html. This is how a stored body escapes the tag’s value. Anything else is
    read as text, so a malformed entry can never print unescaped.

Declaring a tag here gives it no value. Values still come from benecaster_email_merge_tags; a tag you add there should be declared here as well, or an editor cannot offer it.

Parameters

Name Type Default Description
$catalog array — The merge-tag catalogue, keyed by tag name without braces

Returns: array

Example

add_filter( 'benecaster_email_merge_tag_catalog', function ( array $catalog ): array {
    $catalog['member_since'] = [
        'label'       => __( 'Member since', 'my-addon' ),
        'description' => __( 'The date the subscriber joined. Empty when the email is not sent to a subscriber.', 'my-addon' ),
        'types'       => [ 'welcome' ],
        'sample'      => 'March 3, 2025',
        'kind'        => 'text',
    ];
    return $catalog;
} );

Notes

Only declare html for a value that is meant to be HTML. An html tag passes through wp_kses_post() rather than being escaped as text. A tag the catalogue does not know is treated as a URL when its name ends in _url and as text otherwise, never as HTML.

The feed address is {{feed_url}}. There is no {{rss_url}} tag.

Read the whole catalogue, or one email type's tags, with benecaster_get_email_merge_tag_catalog().

Affects

  • The merge tags an email editor lists
  • How a stored email body escapes each tag

Related Recipes

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