Filters and Actions

Newsletter provides actions and filters to third party plugins and themes so they can extend it with new features and integrations.

Filters

newsletter_replace

Called before the standard replacements (of Newsletter tags like {name}) takes place. It receives as first parameter the text to be processed (could be the HTML or text part of a newsletter as well the HTML forms to edit the subscriber profile as well a generic text message).

The second and third parameters are the current subscriber e the current email, both as objects. Both can be null.

To act only on the HTML of outgoing messages, use the newsletter_message_html filter.

add_filter("newsletter_replace", "my_filter_newsletter_replace", 10, 3);
function my_filter_newsletter_replace($text, $user, $email) {
    if ($user) {
        $text = str_replace("{my_tag}", $user->name . ' ' . $user->surname, $text);
    }
    return $text;
}

newsletter_replace_name

Called to change the user name before replacing it using the {name} placeholder. Could be used when the user name is empty to change it to a default value, like “customer” so the typical “Dear {name}” becomes “Dear customer” when the subscriber name is not available.

The same effects can be obtained with the previous more generic filter newsletter_replace.

The second filter parameter is the full user object.

add_filter("newsletter_replace_name", "my_filter_newsletter_replace_name", 10, 2);
function my_filter_newsletter_replace_name($name, $user) { 
    if (!$name) { 
        $name = "Customer";
    } 
    return $name; 
}

newsletter_message_html

This is a filter which receives three values:

• the html message in the way to be sent
• the email object which generated it
• the user object which is the receiver

An example of use:

add_filter("newsletter_message_html", "my_filter_newsletter_message_html", 10, 3);

function my_filter_newsletter_message_html($html, $email, $user) {
   return str_replace('{placeholder}', 'Placeholder replaced!');
}

Warning: the filter should be as quick as possible since it is called for every sent message and the number of messages sent could be really big! So try to avoid database queries, use caches and any good practice to create high speed code!

newsletter_message_subject

See newsletter_message_html. It is invoked for each email sent so the subject can be personalized for each subscriber.

newsletter_profile_url

This filter is called with the profile URL for a specific subscriber just before use it in an outgoing message. The profile URL to filter has already the parameter to identify the subscriber. The second parameter is the subscriber object.

The rare use is if you want to totally change the profile URL to a different profile management. For example if your newsletter database is aligned with CRM database and the CRM has a custom profile page, you may want to address the user to that specific page.

add_filter("newsletter_profile_url", "my_filter_newsletter_profile_url", 10, 2);

function my_filter_newsletter_profile_url($url, $user) {
   return $url . '&param=value';
}

newsletter_send_user

This filter receives in input a subscriber as object and it can be changed just before it is used to compose the final message. For example the user can be enriched with data from another system (like a different name). Changes to the user are NOT stored.

add_filter("newsletter_send_user", "my_filter_newsletter_send_user", 10, 1);

function my_filter_newsletter_send_user($url, $user) {
    $user->name = 'John Smith'; // Very stupid example
   return $user;
}

newsletter_enqueue_style

A true/false filter to totally disable the Newsletter CSS added to the blog public side. Newsletter CSS can be disabled even from the main settings (so maybe this filter will be removed).

add_filter('newsletter_enqueue_style', '__return_false');

The __return_false function is a WP core function to add true/false filters in a compact way.

newsletter_user_subscribe

This filter is invoked BEFORE saving the user after a subscription request. The user is an object and could be an existing user if the repeated subscriptions are allowed. This is not a filter to clock or validate a subscription!

add_filter("newsletter_user_subscribe", "my_filter_newsletter_user_subscribe", 10, 1);

function my_filter_newsletter_user_subscribe($user) {
   // Change something
   return $user;
}

newsletter_message_headers

Invoked for each outgoing email with the current email headers. It receives 3 values: the associative array with the headers, the current subscriber and the current email objects.

add_filter("newsletter_message_html", "my_filter_newsletter_message_headers", 10, 3);

function my_filter_newsletter_message_headers($headers, $email, $user) {
   $headers['X-Custom-Header'] = 'My value';
   // Never forget this!
   return $headers;
}

newsletter_profile_save

This filter is invoked before save the subscriber data as modified by the subscriber it self using the self management page. All values are packed in an associative array with the keys corresponding to the database fields.

add_filter("newsletter_profile_save", "my_action_newsletter_profile_save", 10, 1);

function my_action_newsletter_profile_save($data) {
    // Do something
    // $data['id'] is the subscriber ID
    // $data['email'] is the subscriber email
}

Actions

newsletter_user_confirmed

Invoked when the user status has been changed to confirmed. The user object is already saved and changes won’t take effect.

add_filter("newsletter_user_confirmed", "my_action_newsletter_user_confirmed", 10, 1);

function my_action_newsletter_user_confirmed($user) {
    // Do something
}

newsletter_user_unsubscribed

Fired after a subscriber has been set as unsubscribed.

add_filter("newsletter_user_unsubscribed", "my_action_newsletter_user_unsubscribed", 10, 1);

function my_action_newsletter_user_unsubscribed($user) {
    // Do something
}

newsletter_user_reactivated

Since 6.7.2. Fired just after the user asks to be reactivated when just unsubscribed.

add_filter("newsletter_user_reactivated", "my_action_newsletter_user_reactivated", 10, 1);

function my_action_newsletter_user_reactivated($user) {
    // Do something
}

newsletter_register_blocks

Invoked when it’s time to register custom composer blocks by third party themes or plugins. See the Composer Blocks documentation.