Main Configuration

This page will help you during the configuration of the Newsletter plugin: we want you to get the most out of it! Here, you’ll find an explanation of the parameters you need to set up when you start using the plugin. 

If you have any doubts, please use the support forum to find answers or ask questions!

What's inside

The Newsletter Public Page

The Newsletter plugin needs a WordPress standard page to show its service messages: the activation, the welcome, and the goodbye messages. If you followed the configuration wizard, that page has been created and pre-configured for you automatically.

There is just one simple rule: the Newsletter page should be a regular WordPress page that contains only the [newsletter] shortcode!

For multilanguage blogs, see below for more instructions.

You can find it in your blog page list, where you can also personalize its design depending on your theme features.

If you want to use another page, you have to add the shortcode on that page and reference it on the Newsletter “General Settings” as the public page, so the plugin knows where to redirect the subscribers when they act and when service messages need to be shown. 

If you get a warning about a misconfigured public page and you need anyway to disable that warning, you can add
define('NEWSLETTER_PAGE_WARNING', false);
to your wp.config.php file.

Important notes

  1. If the selected page is deleted or unpublished or if you remove/change the [newsletter] shortcode, it may appear as a 404 error page. In this case, check the configuration!
  2. Do not use any other Newsletter shortcode on the public page (e.g. [newsletter_form]): although the page may look ok, it will not be able to show the service messages! 
  3. If you want to customize the layout of the Newsletter dedicated page, we suggest checking if your theme has the option to change the layout at the page level. You can even create a custom template page in your theme (or in a child theme) or use the same layout of your landing pages, which are usually simpler than the regular ones.
  4. If you add other text to the dedicated page, it will be shown every time a service message is displayed, so be careful!

The Public Page on Multilanguage Blogs

Multilanguage blogs need a bit more attention. The Newsletter dedicated page is created only for the main language with the title “Newsletter”.

If the multilanguage plugin in use is configured to fall back to the main language when a page translation is not available, the dedicated page will work correctly, even if it will show the title and the content in the main language.

If the multilanguage plugin is configured to return a “page not found” when a page is requested in a specific language, you need to create a translation of the dedicated page in every language or set that page to fall back in the main one (it depends on the multilanguage plugin used).

Messages (activation, welcome, goodbye, …) can be translated from the Newsletter administration panels, see more here.

The sender’s email and name

The sender is “who” is sending emails to your subscribers. With “who” we mean a name (for example your name if yours is a personal blog or your brand name, if it is a company blog) and an email address. When you installed Newsletter for the first time, you configured this up through the welcome wizard. 

Use a real email address

Usually, the best choice is to use an email address from your domain with a real mailbox behind it. For example, if your domain is “mydomain.com”, you can create a mailbox or an alias newsletter@mydomain.com.

Some providers do not allow sending emails with a non-existing address at least an alias is required.

Never use an email address from free services like Gmail, Yahoo, AOL, Outlook, and so on. Your blog (server) is not allowed to send emails for those accounts! It can work only if you use an SMTP plugin and configure it to send emails through their services.

Test and test again

Since every provider acts in a different way, once the sender is configured or changed it is important to test the new setup.

Use the Newsletter System>Delivery Diagnostic panel to check if everything is set up correctly, perform a test, and verify if there are any delivery issues.

When emails are not delivered with the configured address

Sometimes it happens that your emails are sent with a different email address or name from the one you’ve set on Newsletter. This may happen for two reasons:

  1. You have a SMTP plugin installed or a plugin that redirects all emails sent from your blog to an external delivery service. Those plugins let you set up an email and name and can eventually overwrite the ones you set on Newsletter. Have a look and disable those options.
  2. You have a plugin which is configured to set specific sender address, like WooCommerce: review the configuration of those plugins (usually they do not interfere with the standard newsletters delivery, but they can change the address when Newsletter sends the activation or welcome messages)
  3. Your provider is overwriting the sender address. It’s a rare situation but it’s worth to ask the provider to check it and have instruction to avoid it.

The Return path

The return path is an email address where all the undelivered messages are returned. If you set a real mailbox as the return path, remember to check it to remove from your lists the addresses that are no longer reachable. The Bounce Addon can do it for you automatically! 

If you use a third-party delivery service (Sendgrid, Amazon SES, Mailgun, …) integrated with one of our delivery addons, you don’t need to set up the bounce checking since it is provided automatically.

Keep in mind that some providers do not allow to specify a return path address since they force their own. And if you use a delivery service they remove your return path and change it with their own to intercept and manage all delivery errors.

Sometimes they provide options to forward to a specified address all that errors as well.

The Reply to Address

The Reply to option is an additional service. You can specify an email where to receive messages if a subscriber wants to reply to your newsletter. 

Be sure that you specify a valid email address. If possible, use an email address from your domain. 

Delivery speed

Max emails per hour

The Newsletter plugin has a delivery engine that sends out emails with a speed up to the configured value. That upper limit avoids email dropping or blocking by providers.

You should always ask your provider which is the limit they will tolerate.

Even on a private server, setting this limit to a reasonable value is a good idea to avoid saturating the server with queued email.

It is not granted Newsletter can send exactly at that speed it is only an upper limit. Slow servers, slow connections, slow SMTPs can set the real speed to a much lower value.

On Newsletter “System” panels you can find an average delivery speed computed from values collected during real deliveries. Those statistics report how many seconds are required to send (by average) a single email and so the speed the plugin can reach.

It is even reported if Newsletter needs to prematurely stop a delivery batch due to limits imposed (by server configurations) on the maximum job duration in seconds (for example there are servers configured to run a single job for a maximum of 30 seconds but the delivery of 100 emails could take more than that).

To have even more evidence of the internal delivery process, the log level on Newsletter main settings can be set to debug and in the “System” panel some logs should be available. Of course reading, those logs require a bit of technical knowledge of the plugin internals.

See the Delivery Engine page for more information about the delivery process.

Advanced settings

Here you can modify some other aspects of the Newsletter, including roles, tracking, and debugging. 

Custom CSS

This function allows advanced users to personalize some aspects of the design of forms, fonts, buttons, etc. Just write down the code and you are good to go. 

Allowed Roles

This option allows you to choose who can access the Newsletter plugin administration functionalities. The options are based on the roles you configured on WordPress (e.g. if you select Editors, every user with the Editor role will have access to Newsletter). Additional roles, other than the standard ones provided by WP, could be created by other plugins (like WooCommerce, User Role Manager, …).

Some functionalities of Newsletter or Addons are available exclusively to the administrator role since they usually need a one-time configuration and may contain sensitive information. An example is the SMTP configuration, the main settings, all delivery addon configuration panels, and many others.

There is not, actually, a fine-tuning access configuration to limit specific functionalities.

Example of roles available in a WP installation

Log level

Every Newsletter component (and even the professional addons) can log their internal state and errors. The log level selects the level of detail those logs should have. 

Debug level can create huge log files. Log files are listed at the bottom of the status panel, where you can download or delete them. Log files are rotated monthly.

Tracking default

It sets the default open and clicks tracking for new newsletters. The value is just a preset, it can be changed on every single newsletter before sending.

IP addresses storage and privacy

This option allows you to select if the IP address of your sites should be stored, anonymized or not stored at all. The IP address is collected at the time of the subscription and is useful to have detailed statistics (read and click tracking). Anonymized IP addresses are changed by removing the last number of the address and replacing it with zero. 

Flood control and geolocation are affected by this settings. If you decide not to store IP addresses, geolocation is less precise and flooding check does not work. 

Debug mode

The debug mode is used just for support operations and required a deep tech knowledge.

It intercepts even the PHP errors and logs them in a specific log file. When in debug mode, an admin warning is always present and the use should be limited to debug sessions. Do not let this mode always be active!

Email encoding

This option defines how an email message is internally encoded. Usually, the default options work perfectly. Sometimes, old mail servers have problems in managing messages with long lines: in this case, try to set it to “base 64”. 

This option has no effects when the delivery is made by and integration addon (e.g. Amazon SES, Mailjet, Sendgrig etc.).

Shortcodes inside emails

This option enables the Newsletter to execute shortcodes that you put inside your newsletter. Of course, shortcodes can generate invalid HTML for an email, so use with care.

This option is useful when you have shortcodes used to generate ad banners that state that they are pure linked images.

To track the opens and clicks and to manage the subscriptions, cancellations and profile editing actions special link are used. Sometimes they’re affected by specific blog settings, caches, protections and so on, so you can change the link format to address some of those issues.

With the standard format, those links direct to the home page with some special parameters, like:

https://www.example.org?na=s&...

Those kind of links can be affected by CDN, caches, optimization plugins that removes the URL parameters (the ?na=s&… part).

Problems

If, when you click a link on a newsletter or submit the subscription, the home page is shown without any other effect, you have a cache blocking the action. You can consider to use the other tracking link format.

Note: when you change the link format, you need to resend the test newsletters so it will include the new links.

The alternative format uses is like:

https://www.example.org/wp-admin/admin-ajax.php?action=tnp&na=s&...

and is uses the standard WP ajax call, both for the admin and public sides. Those links could be affected by plugins or configuration that blocks the wp-admin subfolder.

Problems

Typically, if you get a “forbidden” when subscribing or clicking on a link inside a newsletter, you have the basic auth activate and protecting the admin side. You can solve the problem setting the Newsletter plugin to use the standard format.

Alternatively, since blocking the wp-admin/admin-ajax.php call can affect even other plugins, you can just unlock it (if blocked with a Basic Auth) for example using:

<Files "admin-ajax.php">
    Satisfy Any
    Allow from all
</Files>