Newsletter

Newsletter is a plugin to manage subscriptions and create newsletters directly from your powerful blog.

Newsletter can be extended with some interesting features available with Newsletter Extras package.

Newsletter Plugin is not an alternative of FeedBurner. Read more here.

This page is under revision for new version 2.0.0.

Download

The plugin is available on WordPress Plugin Directory: http://wordpress.org/extend/plugins/newsletter/

Quick start

I have many doubts that a quick start guide can be useful, but I even know many people don’t like to read and understand well how to successfully use a plugin.

• install Newsletter
• create a blog page (50% of malfunctions are due to this step) for newsletter subscription and put in the content the short code [ newsletter ] (without inner spaces and lower case)
• open the page and copy the URL of that page
• insert it in Newsletter Configuration panel and save
• subscribe to your own newsletter going to the subscription page you created, just for a test
• that’s all folks

Help and Support

There is a post dedicated to send questions and get answers.

Should I update?

Many times people ask them self if they have or not to update Newsletter to a new version (usually is WordPress plugins panel that offers such opportunity). Sometime update can be risky, specially if I have introduced new features that may be buggy. So, before update, check articles tagged newsletter to see what’s changed.

Pro version

Newsletter comes in two flavours: free version available as described on WordPress Plugin Repository and a pro version available to members of Satollo.net. From version 2.0.0 (still not released) free and pro version are two distinct plugins. Newsletter Pro replaces Newsletter Extras.

Newsletter Pro has a few interesting features over the free version:

• statistics
• customized forms
• follow up system
• feed by mail

and they are better described on Newsletter Pro page.

Configuration panel

Configuration panel contains the main and general configurations used by Newsletter. It’s important to understand and set such parameters correctly.

Sender name and email. Sender is the “virtual” person who is sending every message related to newsletter, from  subscription messages to newsletters. It’s required to set those two fields (by default their are set with blog name and admin email).

Newsletter page. It’s a WordPress page URL you must create to make Newsletter to work. Such page can have whatever title you prefer, but the body has to contain only the short code

[ newsletter ]

with no inner spaces (between brackets and the word “newsletter”). That page is used to interact with subscribers showing subscription form, messages and so on. As example, my page URL for Newsletter is

http://www.satollo.net/subscribe

See below for more details.

Return path (temporary removed). This is an email address added to every message in a special hidden (but legal) header field. This address is used by mail systems to send back errors (eg. mail delivery error) to notify something is wrong on the destination mail box. Common errors are “mail box full” or “unknown recipient”. Those errors are called “bounces”.
If this field is left blank, the “sender email” is used as return path. WordPress does not set this special header while sending messages, Newsletter, for its messages, changes the behaviour of WordPress mail system to set it.

Test subscribers. Is a list of 5 “name and email” fields used to test many aspects of Newsletter where the most important is the newsletters them self to see if emails comes to test mailboxes and how they render.

Editor access. If you want blog members with editor level to access the newsletter plugin, set this value to “yes”. Pay attention that editor will be able to see and use all functions of Newsletter.

Show panel in english. Configuration panels are originally in English (my poor English), but Newsletter is ready to be translated with default I18N (internationalization – 18 is the number of character between “i” and “n”) of WordPress. If you blog has a different language set (in wp-config.php) and there are a translation in that language, it will be loaded and used. Setting this option to “yes” stops the translation loading.

Logging. Newsletter has an internal log system that writes on file system information on what it’s happening. Usually you can set the log level to “none” so nothing will be written. The level “normal” stores errors and other useful information. The level “debug” writes a lot of information and even sensible data, so it must be used only to… debug! The log file is written inside the Newsletter folder and will be deleted on each update.

Setting up the subscription page

After installing and activating the plugin we firstly need to create a newsletter subscription page. That page is not only for subscription, but it’s used by Newsletter to interact with users.

Follow the steps below:

• open the Pages menu (on the left of your WordPress admin area) and press “add new”
• give a title to the new page, something like “Newsletter Subscription”
• put in the page content the tag [ newsletter ] (with NO spaces between the square brackets and the word “newsletter”)
• publish the page

The page will get a URL which is the value we need to set on “Newsletter page” field. The permalink can be something like http://www.satollo.com/english/newsletter. You can open your new page and copy the address from your browser.

Newsletter page URL configuration

Subscription panel

Subscription process

The subscription process can be configured in two main ways: double opt in and single opt in. In some countries, double opt in is required by law, specially when the newsletters are sent by a company.

Below there are two diagrams that clearly explain what happens when a user subscribe. The first is a double opt in, the second is a single opt int. As you can see there are a number of steps. All those steps shoukd be configured on Subscription panel.

Double opt in subscription process

Single opt in subscription process

Subscription process (with double opt-in) can be broken up in the steps below:

1. a user lands on the newsletter page: this is the subscription step where the users are asked for name and email
2. he types in his data and press “subscribe”: this is the first opt in
3. a message is shown in the page saying the data was stored and an email sent to confirm the subscription
4. the user checks his mailbox and finds a confirmation email with a link to be followed to activate the subscription
5. the user press that link and a “subscription confirmed” message is shown

Text shown in steps 1, 3, 5 are fully customizable within the newsletter Subscription panel.

Pictures are not updated with latest panel version (I made many changes) but the configuration steps are substantially the same.

The subscription form

The subscription form is automatically added inside the newsletter page.

On pictures below there are some examplea of newsletter page as it appears on the subscription step and the configuration panel where to modify the introductory text.

The green box identify the text displayed and where to write it. Click on pictures to enlarge them.

The form is loaded from a language file, so it can be translated. The file depends on your blog language and is one of the ones you find under the folder languages with name xx_YY.php.

Single and double opt-in

You can force Newsletter to work in single opt-in mode, there is a check box on confirmation configuration. It means that a user who leave his email address will be saved as confirmed subscriber and will receive the welcome message.

How to enable single opt-in mode

Name and email or only email

By default, subscription form ask for name and email. On configuration panel you can specify to collect only the email address. This setting change the subscription form and the widget behaviour.

Unsubscription

Unsubscription configuration now let the blog owner to set up a good bye email. If the email subject is empty, the email won’t be sent.

Users unsubscribe starting from a link in a email, usually a newsletter (but unsubscription link can be added to confirmation and welcome emails too).

Widget

To add a subscription for on a sidebar, you can use Newsletter widget. Easy to install and configure, it’ the best way to have a subscription form on all pages.

Composer panel

Testing, Simulating and Sending

First step first, do some tests. On Composer panel there is a “test” button which triggers a newsletter delivery to the test subscribers you configured on Configuration panel.

A test can show you if emails reach the recipient and if emails show up well.

(Temporary removed). When you have a list of subscribers you can simulate. Simulation means to send out a real newsletter to a single test address. How it works? Newsletter will picks up all subscribers from database and compose the email for each of them. Then it sends out that email but forcing the email address (and only it) to the email address configured. Check the Composer panel for such configuration.

Sending. Nothing to say, a real newsletter sending process. No way back when you start a sending process.

Composing emails

The composer panel is rather complex even if at first it seems simple. Mainly the composer is used to create an email (newsletter issue) to be sent. All what is required is a little of fantasi to compose a subject and message body.

In the composer there is a visual editor with it’s advatages and it’s limits. I think for many of us a visual editor is the best choice: you can write, format, create tables, give styles. Just remeber that not all email client (desktop or online) shows text styles as you see them in an editor. Still there are many ways to insert style, inline, referring an exteral file and as an html tag inside a page. Some of them are respected by email client, other removed or totally ignored. This is why many newsletter themes use verbose “inline styles”.

The problem is not obvious, you can find some other info here.

Using visual editor is not only a matter of have it while cmposing, the system reacts in a different way if visual editor is enabled or disabled. Why and how?

Visual editor do not accept <style> blocks (any visual editor, no only TinyMCE), but themes can have (from version 1.4.7) an associated style.css file. So before sending, Newsletter Plugin loads the email body and the theme CSS, merges them and creates a single full HTML email. CSS used is determined by the last theme choosed, so even is you empty the editor content, that CSS will always be added.

If you need to force Newsletter to not use the theme CSS, simple choose the new “Blank” theme.

Avoiding visual editor

From version 1.4.7 you can disable the visual editor of composer and write the full html text of your email. Newsletter plugin, while sending, will use your email body AS-IS so you are free to make whatever you want. Having control of the html code, you can insert <style> blocks too, but be aware that not all email client will respect it.

To disable visual editor check the “Disable visual editor” checkbox and save. Remember to save!

Batches explained

One of the biggest problem with hosting provider are limits they impose on emails sent per hour. So there is a configuration where you can set the max number of email to be sent per batch. If the limit is reached, Newsletter stops the sending process and show a “batch info” with a button to restart the sending process.

Batch info box, shows the number of emails sent, the number of email still queued, the last subscriber email address and id processed. There is and internal system that tries to save batch state even when the system if stopped by errors or other provider limits. I did my best, but I know I won’t be enough…

For who has the Extras package, simulation and sending can be scheduled breaking the process on small batches started every 10 minutes. Combining this fragmentation with a maximum number of email per batch you can avoid to go over provider limits.

Lists panel

I have to be honest I don’t like lists and I originally left out lists from my plugin to keep it simple. Lists are hard to manage, create a number requests due to different ways users want to have them implemented.

I tried to add them in the safest and simple way. If one does not need lists, simple he can ignore them and the plugin works as if lists were not present.

If you want lists… ok, you can configure up to 9 lists. Lists are NOT user groups. Lists are more like “options”. An user can be associated to one or more lists to express it’s interest in specific topics and, of course, blog owners can send a newsletter to a specific list.

Some lists can be private: that means only the administrator can add a user to such lists.

To make list “checkboxes” available on subscription form, I rewrote it in a new format and I added a lot of code to manage that new format (this is why I hate lists…). That big change created a new opportunity: now form labels trabslation can be done directly on a new configuration panel.

Import panel

May be a blogger already has a list of subscribers to be used. So there is the feature that permits to import such list of user.

The import process and the data needed is really simple: a csv formatted text with email and name. Using the “import” panel, just past the csv text in the textarea and press import.

The import process doesn’t check for YOUR data validity, but can give as a result a number of “error” lines.

A line is wrong, eg, when the email address in it is already in the database. Emails need to be unique.

The cvs format is “email;name”, eg.:

info@satollo.com;Stefano Satollo
…

email and name has to be separated with a semicolon (yes I know the CSV means “comma separated values”). CVS text has to be copied in the import textarea, no file upload is available. Emails imported will be normalized and token for unsubscription process generated.

From version 2.0.0 on importing you can specify the lists to be associated to imported subscribers.

Lists selection during import

Export

There is a specific sub page of Newsletter which lists out all subscribers in CVS format to be saved or processed elsewhere. The exported text has one subscriber per line with email, name, status and token. The status can be one of S or C character. S stands for “subscribed but not confirmed”, C stands for “subscribed and confirmed”.

Labels panel

The label panel simplifies translation and customization, giving the freedom to change subscription form labels (and may be some other message).

Themes

Version 1.4+ has a new theme system, made of PHP files that can be fully programmed. Newsletter comes with two themes stored on “themes” folder under the plugin folder.

Each theme has its own folder with (at least) a “theme.php” file inside. Just look at them as starting base to understand how they work and to create your own theme.

From version 1.4.7, theme system supports CSS. In a theme folder it’s possible to add a file named “style.css”. It has to be like a common CSS file for web sites.

When sending a newsletter issue, this CSS will be loaded and merged with message body. Be sure to read here to know more about how CSS are used by different email clients.

On composer paragraph it’s explained how CSS are treated while creating messages with or without the visual editor.

Theme folder has this format:

theme-folder-name
-- theme.php (mandatory)
-- style.css (optional)
-- [other files or folders]

To create a custom theme you MUST NOT modify the packaged themes, otherwise on next update the changes will be lost.

To customize Newsletter themes just create a folder named “newsletter-custom” inside the “wp-content/plugins” folder. Inside that folder, create a “themes” folder and copy one of the packaged theme folder inside it. You may change the folder name as it’s used as theme name.

Those custom themes will be listed in composer page.

All theme files (usually images) need to be stored in theme folder.

I hope there will be some designers who want to share they newsletter themes, I’ll be happy to add them to Newsletter package.

Versions

In deep notes on version can be found under tag “newsletter“. Versions description may be missing in this page section. Use the previous link to have full documentation.

Remember the plugin firstly load the en_US.php file and then the one specific for the blog language.

If you want to customize the form, it’s simple: do not modify the file provided with the plugin. Insted, create a folder named “newsletter” under the folder “wp-content”, and a subfolder “languages”. Copy the language file you want to start with under the latter folder and rename it “custom.php”. Change the content as you like.

Why put the file sin that folder? Because when you upgrade the plugin, WordPress delete the original folder!