Create custom merge tags for the MailerPress email editor

You can create custom merge tags for the standard MailerPress email editor by registering a group in PHP. The group then appears in the editor’s Personalization Tags picker, and MailerPress resolves its tags for each recipient when sending a campaign or automation email. This feature is available in MailerPress Free; Pro is not required.

Register a custom merge tag group

Add the following snippet to an active custom plugin or site PHP code that loads on every request, including scheduled email processing. Register the group on WordPress’s init action and check that the MailerPress function exists before calling it.

add_action( 'init', static function (): void {
	if ( ! function_exists( 'mailerpress_register_merge_tag_group' ) ) {
		return;
	}

	mailerpress_register_merge_tag_group(
		'member',
		'Membership',
		[
			'name'        => 'Member name',
			'account_url' => [
				'label' => 'Account URL',
				'type'  => 'url',
			],
		],
		static function ( string $key, object $contact, array $context ): string {
			if ( 'name' === $key ) {
				return (string) ( $contact->first_name ?? '' );
			}

			return home_url( '/my-account/' );
		}
	);
} );

Replace /my-account/ with your site’s account page path. The example reads the recipient’s first name for member.name and supplies a URL for member.account_url. The callback receives the tag key, a contact object, and a context array; use that context only if your own tag logic needs it.

The registration function accepts a group key, a group label, tag definitions, and a callback, and returns a Boolean. Group and tag keys must start with a lowercase letter and then contain only lowercase letters, digits, or underscores. Supply a nonempty label and at least one tag; register each group key only once. A tag may be defined as 'key' => 'Label', which defaults to the text type, or as an array with a label and a type of text or url.

Insert the tags in the email editor

1. Open a standard campaign or automation email in the MailerPress editor and place the cursor in a rich text area.
2. Click Personalization Tags in the rich text toolbar, select Membership, then choose Member name and click Insert.
3. To use the account URL as a hyperlink, choose Account URL and click Insert as link.

You can also enter the merge tag syntax directly: {{member.name}} or {{member.account_url}}. These custom groups appear in the standard campaign and automation editor; the specialized WordPress email and WooCommerce email picker modes do not list them.

Set a default value

Click an inserted tag in the editor to open Default value for tag. Enter a value to use when the tag has no result, or choose Leave empty if none, then click Update.

In the brace syntax, {{member.name default="friend"}} uses friend as its fallback. Add defaults only with the {{...}} form; the alternative percent-style tag syntax does not support a fallback.

Check the result with a real recipient

MailerPress resolves custom merge tags for each recipient in campaign and automation email subjects and bodies. Check an actual recipient’s delivered email to confirm the callback returns the expected name and link. The editor’s test email replaces dynamic tags with their fallback or an empty value without running your callback, so it cannot verify recipient-specific output.

Return a scalar value or an empty string from the callback. MailerPress escapes text values as HTML and url values as URLs. A non-scalar result or an exception produces an empty replacement, so ensure the callback can run during scheduled sends.