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 . '¶m=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.