Skip to main content

benecaster_get_email_merge_tag_catalog()

Utilities Free 
benecaster_get_email_merge_tag_catalog( ?string $type = null ): array

Describes every merge tag an email can carry, so an editor or a settings screen can list them: for autocomplete, for descriptions beside the field, and for the simulated data a preview uses.

It describes the tags; it does not supply their values. Values are filled in at send time from the email’s own data and the benecaster_email_merge_tags filter.

Parameters

Name Type Default Required Description
type string|null null No An email type slug, for the tags that email can carry, or null for every tag.

Return Value

Type: array

Keyed by tag name, without braces. Each entry has label, description, types (the email types it appears in; an empty list means a global tag, in every email), sample (the value a preview or test send uses) and kind (text, url or html: how a stored body escapes it). With a type, the global tags plus that type's own; without, all of them.

Example

foreach ( benecaster_get_email_merge_tag_catalog( 'welcome' ) as $tag => $entry ) {
    printf(
        '<li><code>{{%s}}</code> %s</li>',
        esc_html( $tag ),
        esc_html( $entry['description'] )
    );
}

Notes

Declaring a tag gives it no value. An add-on that adds a tag through benecaster_email_merge_tags should also declare it through the benecaster_email_merge_tag_catalog filter, or an editor cannot offer it. An entry missing a key is completed safely: no types (a global tag), an empty sample, and text.

A global tag can still be empty in a particular email, such as subscriber_name when there is no account, or unsubscribe_url in a transactional email. Each description says when.

kind is how a stored body escapes the value: text as plain text, url as a URL, and html through wp_kses_post(). Only custom_message is html among Benecaster's own tags.

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

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