Filters, Actions, Tables

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

What's inside

Filters

Filter “newsletter_subscription”

This filter receives an object of the class TNP_Subscription representing a subscription started from a from or an integration (for example with a form manager, WooCommerce, …).

The object contains the property $data with the subscriber’s information (name, email, …) and some properties that determine how the subscription should work (opt-in mode, antispam checks, and so on).

The filter receives as a second parameter the subscriber already registered identified by the subscription email. That helps in deciding how to change the standard subscription behavior when a subscriber is already present.

The object fields are described on plugin sources (file includes/module.php).

add_filter("newsletter_subscription", "my_filter_newsletter_subscription", 10, 2);
function my_filter_newsletter_replace($subscription, $user) {

     // Another filter nulled the subscription
     if (!$subscription) {
          return $subscription;
     }

    // Just an example: if the subscriber exists, force the single opt-in 
    if ($user) {
        $subscription->optin = 'single';
    }

    // Never forget the return!
    return $subscription;
}

If the returned value is “null” the subscription process is ended.

Filter “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) {
    // Always check if the user is present 
    // (the replace can be called even on contexts where the user is not available)
    if ($user) {
        $text = str_replace("{my_tag}", $user->name . ' ' . $user->surname, $text);
    }
    return $text;
}

Filter: newsletter_replace_name

Obsolete, please use the newsletter_replace filter and act on the $user->name. See above.

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; 
}

Filter “newsletter_message”

This filter is fired every time a message is created for a subscriber and just before sending it. $message is an object with all fields required to create the final email: subject, HTML part, text part, headers, and so on.

The filter receives not only the message but even two other objects: the subscriber and the email from which the message is derivated. All Newsletter tags (like {name}, {email}, …) are already replaced when the filter is fired.

With this filter, you can change every element of the message, from the body to the headers. See this example on GitHub about adding a Bcc address.

Here a snippet of code you can use directly.

add_filter("newsletter_message", "my_filter_newsletter_message", 10, 3);

function my_filter_newsletter_message($message, $email, $user) {
   // Do something with the HTML part of the message
   $message->body = ...;
   return $message;
}

Filter “newsletter_message_html”

Obsolete, please use the newsletter_message filter and act on the $message->body. See above.

This is a filter that 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!

Filter “newsletter_message_subject”

Obsolete, please use the newsletter_message filter and act on the $message->subject. See above.

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

Filter “newsletter_message_headers”

Obsolete, please use the newsletter_message filter and act on the $message->headers. See above.

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;
}

Filter “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';
}

Filter “newsletter_send_user”

This filter receives in input a subscriber as an 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($user) {
    $user->name = 'John Smith'; // Very stupid example
   return $user;
}

Filter “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.

Filter “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 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;
}

Filter “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

Action “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
}

Action “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
}

Action “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
}

Action “newsletter_user_complained”

Since 8.5.9 and with updated delivery addons.

It is fired when the subscriber status is changed to complained (reported by an external delivery system).

add_filter("newsletter_user_complained", "my_action_newsletter_user_complained", 10, 1);

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

Action “newsletter_user_bounced”

Since 8.5.9 and with updated delivery addons.

It is fired when the subscriber status is changed to complained (reported by an external delivery system).

add_filter("newsletter_user_bounced", "my_action_newsletter_user_bounced", 10, 1);

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

Action “newsletter_send_end”

This action is triggered when a newsletter is sent and it is moved from the “sending” to the “sent” statuses. 

add_filter("newsletter_send_end", "my_action_newsletter_send_end", 10, 1);

function my_action_newsletter_send_end($email) {
    // Do something
}

The composer

Action “newsletter_register_blocks”

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

Tables

The Newsletter plugin stores part of the data (subscribers, newsletter, …) on specific tables inside the WP database, alongside the WP tables. Some maintenance operations, not available in the admin panels, can be done directly into the database.

The Newsletter plugin table names are prefixed with the tables’ prefix configured in the blog wp-config.php file.

Please, be sure to backup every table you’re going to modify and to know how to restore it if needed.

Subscribers table

Its name is wp_newsletter and contains all the subscriber fields.

  • id – is a unique surrogate identifier that never changes
  • email – is the email address and it is indexed as unique (no two identical email addresses are allowed)
  • list_N – is a “flag” determining if the list N is active (1) or inactive (0)
  • profile_N – they’re string fields (max 255 characters) containing the custom fields data

If you need to clean up a custom field, for example, the number 3, you can run the query:

update wp_newsletter set profile_3=''

If you need to reset the list 5 of all subscribers (it can be done from the maintenance admin panel, as well):

update wp_newsletter set list_5=0

The SQL language lets you create complex updates. For example, a simple one to set list 6 for every subscriber NOT in list 5:

update wp_newsletter set list_6=1 where list_5=0