MailerPress hooks and filters reference

MailerPress fires WordPress actions and filters (hooks) that let developers react to contact, campaign and tracking events, adjust queries and limits, and connect MailerPress to their own code. This page lists the main public hooks of MailerPress and MailerPress Pro, by topic, with their arguments. Hooks not listed here are internal and may change without notice.

Most hooks below are part of MailerPress (free). Hooks in sections marked “(MailerPress Pro)” only fire when MailerPress Pro is active.

Where to add your code

Add your snippets to a custom plugin, a must-use plugin (wp-content/mu-plugins) or the functions.php file of a child theme. Many MailerPress events run in the background through Action Scheduler, so load your code on every request, not only in the admin. When a hook passes several arguments, set the number of accepted arguments in add_action() or add_filter().

Contacts and subscriptions

Example: run your own code when a contact receives a specific tag.

add_action( 'mailerpress_contact_tag_added', function ( $contact_id, $tag_id ) {
	if ( 12 !== (int) $tag_id ) {
		return;
	}

	// Notify your CRM, log the event, etc.
	error_log( sprintf( 'MailerPress contact %d received tag %d', $contact_id, $tag_id ) );
}, 10, 2 );

Add a contact from your own code

add_mailerpress_contact() creates a contact, or updates it if the email address already exists. Pass at least email; you can add first_name, last_name, lists and tags (IDs) and opt_in_source. Without lists, the contact goes to your default list. Without subscription_status, MailerPress applies your sign-up confirmation setting: with double opt-in enabled, the contact is pending and receives the confirmation email. The function returns an array with success and contact_id, or success and error.

function my_plugin_subscribe( $email, $first_name ) {
	if ( ! function_exists( 'add_mailerpress_contact' ) ) {
		return;
	}

	$result = add_mailerpress_contact( [
		'email'         => $email,
		'first_name'    => $first_name,
		'lists'         => [ 2 ],
		'tags'          => [ 5 ],
		'opt_in_source' => 'my_plugin',
	] );

	if ( empty( $result['success'] ) ) {
		error_log( 'MailerPress: ' . $result['error'] );
	}
}

Campaigns

Tracking and bounces

Bounce webhooks from email service providers (MailerPress Pro)

MailerPress Pro receives bounce notifications (undeliverable emails) from your email service provider. An unsigned notification is applied only if the site recently sent an email to that address through the same provider, and only up to an hourly limit. These filters adjust that protection.

Email editor and content

To add your own personalization tags, use mailerpress_register_merge_tag_group(), described in Create custom merge tags for the MailerPress email editor.

Example: remove pages from the content you can insert into emails.

add_filter( 'mailerpress_post_types_public', function ( $post_types ) {
	unset( $post_types['page'] );
	return $post_types;
} );

Subscription pages

mailerpress_pages_rendered_content (filter) receives the HTML generated by the [mailerpress_pages] shortcode and an array with action (confirm, confirm_unsubscribe, manage, reengagement_confirm or unsubscribe), atts (shortcode attributes) and is_preview. Return the HTML to display. To design these pages without code, see Design the Manage Subscription and Unsubscribed Pages in MailerPress.

Automations

Start an automation from your own code

The Custom Hook trigger starts an automation when a WordPress action fires. By default, it accepts hook names that start with mailerpress_custom_. In the trigger settings, enter the Hook Name and choose the type of each parameter (Email Address, User ID, Contact ID or Custom Data); the Code Example field shows the matching do_action() call. With an email address, MailerPress creates a pending contact if the address is unknown. The automation must be created by an administrator and enabled.

// Parameter 1 Type: Email Address
do_action( 'mailerpress_custom_course_completed', $user_email );

To use an existing hook name that does not start with mailerpress_custom_, allow it with the mailerpress/workflows/allowed_custom_hooks filter:

add_filter( 'mailerpress/workflows/allowed_custom_hooks', function ( $hooks ) {
	$hooks[] = 'my_plugin_order_validated';
	return $hooks;
} );

Automation filters and actions

The automation classes are in the MailerPress\Core\Workflows\Models (AutomationJob, Step) and MailerPress\Core\Workflows\Results (StepResult) namespaces. For example, $job->getAutomationId() returns the automation ID.

Webhooks (MailerPress Pro)

See the MailerPress Webhooks Guide for the list of events and the payload format.

Form integrations (MailerPress Pro)

Contact imports

Lower these values on a small shared hosting plan if imports time out.

Security, settings and administration

Example: your site is behind a proxy at 203.0.113.10, and you don’t want MailerPress to load promotions.

add_filter( 'mailerpress_trusted_proxies', function ( $proxies ) {
	$proxies[] = '203.0.113.10';
	return $proxies;
} );

add_filter( 'mailerpress_remote_promotions_enabled', '__return_false' );

To manage contacts and campaigns from another application, use the MailerPress public REST API. For command-line tools, see MailerPress WP-CLI commands.