Using Jetpack for E-mail Subscriptions in WordPress

You can find a bunch of “subscribe to posts” plugins in the WordPress.org directory but from my personal experience, it’s very difficult to find something as good and reliable as Jetpack.

The major difference is behind the scenes — when most post subscription plugins will use the wp_mail function to distribute your new post (using sendmail from your server or an SMTP account,) Jetpack will simply send your new post to the WordPress.com server, which will take care of the distribution for you.

Why does that matter? I can name several reasons:

• The WordPress.com mail servers can handle far more load than your shared hosting server, VPS or dedicated server, so e-mails will (most likely) be delivered on time and to everyone.
• People enjoy reading posts from one place. RSS feeds is a good option, but so is the WordPress.com Read module.
• People can manage their WordPress.com and Jetpack-powered subscriptions in one place, choose between immediate e-mails, daily digests and IM notifications, as well as choose between HTML and plain text e-mails.
• You can use Stats in Jetpack to track your blog followers.

However, there are drawbacks too, the major one of which, is that you don’t have control over the actual markup in the e-mail that’s being sent, so no advertising, changing colors and so on. But, we can live without that, right? :)

The Subscription Form

The easiest way to enable e-mail subscriptions, is to use the sidebar widget that Jetpack comes with. You can find a great tutorial on the Jetpack website, however, today I’d like to show you how to totally customize that part by using your own form, handler and calls to the Jetpack API.

Note that to get this working, you will need public WordPress site with Jetpack enabled and linked to your WordPress.com account. So let’s begin with a simple form, somewhere in your theme template files:

<form method="POST">
    <input type="hidden" name="my-form-action" value="subscribe" />
    <input name="my-email" value="" placeholder="Enter your e-mail" />
    <input type="submit" />
</form>

That’s easy enough to understand, right? A hidden field that would tell us when the form is submitted, an input field for the e-mail address and a submit button. A nonce field would be very useful too, but let’s try and keep it simple.

The Subscription Form Handler

Next, you will need something that will handle the form submission, somewhere in your theme’s functions.php file or preferably a plugin file (here’s why.)

add_action( 'init', 'process_my_subscription_form' );
function process_my_subscription_form() {
    if ( isset( $_POST['my-form-action'] ) && $_POST['my-form-action'] == 'subscribe' ) {
        $email = $_POST['my-email'];
        $subscribe = Jetpack_Subscriptions::subscribe( $email, 0, false );
        // check subscription status (to be continued)
    }
}

This is quite simple to follow along too, we’re checking whether the form was submitted and then using the subscribe method of the Jetpack_Subscriptions class, which takes three arguments — e-mail address, a post ID (if you were subscribing to comments) and a boolean value for async versus sync calls. You shouldn’t worry about these for now.

This form handler, together with the above form, will already allow users to input their e-mail addresses and hit the submit button. They’ll get a notification to their e-mail address to confirm their subscription, and if they do, they’ll start receiving new posts from your website. Hurray! But wait…

Subscription Status Feedback

The problem, however, is that we haven’t provided any feedback about their subscription: was it successful, or are they already subscribed, or maybe they entered an invalid e-mail address. For this purpose, we should look at what the Jetpack subscribe method returned, and check for success or errors.

We don’t have to reinvent the weel here, but rather use the same code that is used in Jetpack’s e-mail subscriptions widget, right after calling the subscribe method:

// check subscription status
if ( is_wp_error( $subscribe ) ) {
    $error = $subscribe->get_error_code();
} else {
    $error = false;
    foreach ( $subscribe as $response ) {
        if ( is_wp_error( $response ) ) {
            $error = $response->get_error_code();
            break;
        }
    }
}

if ( $error ) {
    switch( $error ) {
        case 'invalid_email':
            $redirect = add_query_arg( 'subscribe', 'invalid_email' );
            break;
        case 'active': case 'pending':
            $redirect = add_query_arg( 'subscribe', 'already' );
            break;
        default:
            $redirect = add_query_arg( 'subscribe', 'error' );
            break;
    }
} else {
    $redirect = add_query_arg( 'subscribe', 'success' );
}

wp_safe_redirect( $redirect );

Although quite long, the code above is very easy to understand. We’re checking the $subscribe variable (returned from Jetpack) for whether it’s an error or an array of errors. If it’s an error, we read the error code, and change the subscribe query argument accordingly, with add_query_arg. This will add, for example, ?subscribe=invalid_email, to our current URL.

If there was no error, we use success for that very same query argument. Finally, we redirect to our newly constructed URL. It’s much easier to understand when you’ll see this in action.

At this point, you can test again by trying to subscribe, and you’ll see that the page is being redirected with the subscribe query argument added each time, showing the status of the subscription. Go ahead and enter an invalid e-mail address.

The Subscription Form (again)

Let’s return to our theme template where we rendered our subscription form and tweak it a little bit, based on our subscription status:

<?php $status = isset( $_REQUEST['subscribe'] ) ? $_REQUEST['subscribe'] : false; ?>
<?php if ( $status == 'invalid_email' ) : ?>
    <p>You have entered an invalid e-mail, please try again!</p>
<?php elseif ( $status == 'success' ) : ?>
    <p>Thank you for subscribing! Please check your e-mail to confirm.</p>
<?php else : ?>
    <form method="POST">
        <input type="hidden" name="my-form-action" value="subscribe" />
        <input name="my-email" value="" placeholder="Enter your e-mail" />
        <input type="submit" />
    </form>
<?php endif; ?>

The first line will read the status into a variable, and then a check for the status with the relevant messages. I haven’t included all statuses for brevity, but you should have a couple more elseif blocks for “already” and “error”. Voila!

What’s next? Well it’s up to you: you can customize the form however you like, you can redirect your visitors to a “thank you for subscribing” page (in the form handler,) or you can even send them an e-mail thanking them for their subscription :)

That’s about it! What’s your favorite way to handle e-mail subscriptions on your blog? What about newsletters, have you tried Jetpack to send out newsletters, or have you got a different preferred way? Share your thoughts and thanks for stopping by!