The Subscription

Use the  forum to discuss or ask for help, thank you!

Everything starts with a subscription: someone fills in a form with his email (and eventually few other fields) and submits his data. So the first step is to expose a form and then to configure the subsequent flow of events:

  1. error messages for invalid data or already registered email
  2. confirmation request message and email (with activation link)
  3. welcome message and email on successful confirmation
  4. profile page where to change or integrate the data with other fields

On this page we’ll go through:

  1. Subscription start points: what are and how to create them
  2. 500/404/fatal error on subscription
  3. Single and double opt-in: what’s that?
  4. Confirmation page and activation email
  5. Welcome page and welcome email: what to put in them
  6. Use the blog theme for subscription step messages or change the default appearance
  7. Change the default skin of emails sent during the subscription process
  8. All about unsubscription
  9. The profile edit page

Subscription start points

A subscription starts where there is a subscription form. A subscription form just shows some fields (at minimum the email field) and a submit button.

Use the widget

The simpler way to add a subscription form to your site is to add a Newsletter widget to your sidebar.

The newsletter widget will show a subscription form following the rules you set on form fields configuration (see later about this topic). You can even recall your custom forms instead of the standard one, using the tag {subscription_form_N} (new tag of version 3), where N goes from 1 to 10 or make the standard widget form appear where you want inside the configurable text using the tag {subscription_form}.

Those tags work only if used in the Newsletter widget text!

Note that the subscription form generate by the widget is aesthetically different from the one generate on other pages (to be more compact).

Use a dedicated page

Many times sites have a standard subscription page where visitors can sign-up for the newsletter. It’s simple: create a standard WordPress page and insert into it the short code [newsletter_form]. This short code accepts (optionally) the “form” attribute indicating you want a specific custom form (from 1 to 10): [newsletter_form form="N"]

This short code can be used in posts as well and repeated in different posts or pages and eventually many times in the same post/page.

Inside posts

If you want to have the subscription form inside every post (for example on bottom of them) you can use a plugin like Header and Footer and configure it to inject the short code in every post.

The subscription form on external sites

This activity require some HTML skills.

The subscription form is simply a piece of HTML. A special panel of the Subscription Module gives you the full code created using the rules set on form fields panel: you can copy it as is or changing the HTML structure as you need. Just remember: the fields names must be reserved.

Technical notes

The subscription forms send the data to a special URL managed by Newsletter which starts the subscription flow:


The subscription flow is automatic, no manual action are required, and you can tune it on your needs as explained below. It’s important to ave that URL working, but sometime it may be blocked by security plugins or file permissions errors or other odd technical problem. Since the wide variety of installations we met, the next paragraph is dedicated to solve this special problem.

The subscription messages

After the email submission, the Newsletter plugin shows a message (a confirmation request message or a welcome messages, it depends on your opt-in mode choice).

Those message, if not elsewhere configured, are shown on a simple and blank page. To have a real blog page dedicated to show those messages (and the unsubscription sequence messages as well), you can create a page, put in it only the [newsletter] short code and set its link on the general subscription steps panel.

That panel has a button that creates the page automatically for your convenience.



This page, if opened directly, shows a standard subscription form, so it can be used even as landing page for subscriptions starting point.

500/404/fatal error on subscription

We anticipate this topic because it’s important to solve subscription issues as soon as they appears.

Subscribers data is sent from subscription forms to a Newsletter PHP file, named “subscribe.php” which can be found in to the “do” folder of the plugin (something like http://www.domain.tld/wp-content/plugins/newsletter/do/subscribe.php).

Some providers force the permissions of plugin files so they can’t be executed (while it is absolutely legal to execute them!) and then the subscription process ends with an error.

If the provider has a control panel where you can restore the file permissions, use that feature. If not, try to ask them reporting exactly how to reproduce the problem.

Other situations of failing subscription is caused by security plugins which, for some reasons, believe the subscription process is an hacking attempt. Try to disable them to see if that is the case and then contact the author to know how to reconfigure them in the right way.

Other blocks can be caused by server level security configurations (like Apache modules) which, as in the previous example, wrongly detect a subscription as an hacking attempt. In this case the system administrator is required.

Single and double opt-in: what’s that?

Single opt-in and double opt-in are two different subscription processes: the first simple collect the email and gives a welcome message, the second pretends that email to be real and owned by the subscriber: it requires the user to confirm that.

The confirmation is obtained sending a special activation email to the subscriber with a link he must click to complete the subscription.

Double opt-in, other than a good practice, is a law requirement in many countries and of many hosting providers.

Repeated subscriptions

Changed on version 3.9.

When a user attempt to subscribe with an already stored email, the subscription proceeds as a normal subscription but the collected data (for example the name or the preferences) is stored in a temporary area. When the confirmation is activated by the subscriber (from the confirmation email), that data is merged with the original subscription.

That simplify a lot the multiple subscriptions which are useful to offer different landing pages where the same subscriber could land at different times. It solves even the problem of subscriber which sign up for a giveaway or a gift and after sometime they resubscribe because they forgot to be already registered of because they lost your gift (for example an e-book).

Confirmation page and activation email

If you chose, as you should, the double opt-in, you should configure some messages that help the subscriber to complete his registration. The confirmation message is shown to the user after the email submission and should contain a notice about the activation email he should find in his mailbox. Remember to remind to check the spam folder when looking for that email.

You should even prepare the activation email, a simple message with a link to complete the activation. That link, created by Newsletter, is represented by a tag: {subscription_confirm_url}.

Welcome page and welcome email: what to put in to them

When the single opt-in is active or when the user confirm his subscription from a double opt-in process, he lands on the welcome page and receive a welcome message. Both are configurable on Subscription Module panels.

Welcome email can be disable setting the subject to blank.

If the subscription to the newsletter is promoted with a give-back (for example a discount code or a link to a free ebook), those should be exposed on welcome page and welcome message: with double opt-in you’re sure you have a real and owned address in your database.

With single opt-in, the bonus should be inserted only on welcome email, since that forces the subscriber to insert an address he can read.

Use the blog theme for subscription steps

Messages are shown by Newsletter on a blank page, not actually very nice. If you prefer you can dedicate a WordPress page for that just creating a page an putting in it only the short code [newsletter].

It’s not enough: the address of that page must be set on Subscription Module panels otherwise Newsletter won’t know about the existence of that page.

From now on the subscription messages will be shown themed with your blog skin.

The created page, when opened directly, acts as a subscription staring point showing the subscription form, so it can be used as a single all in one page.

If you like the separated pages when Newsletter shows messages, you can change their layout t be recall your colors and design. To do that you must work with Newsletter files: inside the  subscription folder (of the plugin package) there is a “page-alternative.php” file. That file is an example that can be modified to “skin” the massages pages.

Open what file with a text editor and read the instruction at the top of it.

Change the default skin of emails sent

Activation and welcome emails are in HTML format, even if they appear really simple. That means you can make them a little bit better, changing fonts, colors and layout. To change that layout see the file “email-alternative.php” inside the subscription folder of the plugin package. Read the instructions at the top of it.

All about unsubscription

Unsubscription always starts from a message sent by Newsletter. On every newsletter you sent you should add the {unsubscription_url} tag which is converted in a per subscriber links which, once clicked, starts the unsubscription process.

That tag can be used on welcome email as well.

The cited link brings the user to a page where he’s asked if he really want to unsubscribe. He will confirm it clicking on another link generated by the tar {unsubscription_confirm_url}. Sample texts and emails already have them, just customize the texts.

If you prefer to have on emails an immediate unsubscription link, use the {unsubscription_confirm_url} directly: users won’t be asked to confirm adn unsubscribed directly.

Unsubscribed users are not deleted from the database, but moved to status “unsubscribed”.

The profile edit page

If you use a complex subscriber profile (with preferences and profiles), you may want a subscriber to be able to change them. The special tag {profile_url} that you can add on every emails (and even on welcome email), drives he to a page with a form where to edit his data.

The email can never be changed.

The profile page is configurable on Subscription Module panels and must contain the {profile_form} tag with eventually other text. That tag is replaced with the profile form automatically generated by Newsletter.

That tag can be used even on welcome page, so you can thank you the user for the subscription and propose to complete his profile: usually it’s better than asking a lot of information on subscription moment.

Subscription on registration

Newsletter, optionally, can offer newsletter subscription to users which are registering to the site. The site registration is usually required to use the forums, to comment, to shop.

There are few options to decide how this integration works:

  1. The subscription is “forced” asking nothing to the registrant
  2. The subscription is offered with a check box (eventually already checked)

When a subscription is inserted during registration it is inserted in not confirmed status. This choice is almost mandatory, since the email used during registration cannot be considered owned by the registrant until he confirm it.

Imagine someone using your email to register to blogs which start to send you newsletter. Not very nice, isn’t it?

WordPress is smart and controls those situations sending the password to new registered used to the specified email address. If the user can access the mailbox to get the password, the email address is owned by him.

Newsletter does not send it’s own confirmation email, it would be excessive for the registrant. Instead Newsletter listens to log-in events and when a new registered user access the site (hence he got the password from the WordPress new account email), his subscription is changed to confirmed.

Silently we can confirm subscription without hassle the users with other actions.

Of course this is a double opt in which is always applied with this kind of integration between the WordPress registration and the Newsletter subscription (even when a blog uses the single opt in).