Mailchimp Signup Form for WordPress

If you like to offer a newsletter for your website’s visitors, Mailchimp is one of the first choices because of the great interface they offer. If you like to include the signup form in your WordPress website it’s possible to use their plugin or you can add some HTML code using the default WordPress text widget. In the past we posted an article about how to use the Mailchimp API together with your contact form script. Today we use the same kind of script to integrate the signup form in WordPress. You can check my working Mailchimp signup form on this website (it’s double opt-in signup, if you don’t like to subscribe just ignore the mail which is send by Mailchimp).

Why should I use the Mailchimp API for the signup process?

There are different methodes to include the Mailchimp signup form in your WordPress website:

Mailchimp plugin or widget

A Mailchimp plugin is very easy to integrate in your WordPress website and works fine for many cases. If you need more “freedom” you should know that there are limitations: You can style your form a lot using CSS but you can’t use your own HTML code. The settings page offers a lot features, but the advanced user will always use a feature in a different way. If you don’t like to write code, USE this plugin!

Mailchimp forms for your website

In the Mailchimp section “Lists” is a sub-section that offers 3 different forms for your website. A basic form which is great if you like to use your own design, a classic form which will use the style from your Mailchimp list configuration and the “Super slim form” with cool Ajax effects. You can use them all within WordPress if you include the code right in your WordPress theme.

Using the Mailchimp API

If you like 100% freedom in your design and application you need to use the API system. This way it’s your choice how to integrate the form in your website. In this tutorial I create a WordPress shortcode that will build a form in a page, widget or theme. The used code is able to communicate with the WordPress Ajax API system.

Preparations

Before you follow this tutorial you need a self-hosted WordPress installation, a working Mailchimp account, a working mailing list and also a Mailchimp API key.

Mailchimp signup form

I like to use a form right in my post or page using jQuery to process the form request. I create a simple form with 3 fields: First name, last name and the email address. Place this shortcode in your functions.php file:

function createMCForm() {
	return '
	<div id="formcont">				
		<form id="myform">
			<p>
				<label for="name">First name:</label>
				<input type="text" name="name" id="name" size="30" />
			</p>
			<p>
				<label for="lname">Last name:</label>
				<input type="text" name="lname" id="lname" size="30" />
			</p>
			<p>
				<label for="email">E-mail:</label>
				<input type="text" name="email" id="email" size="30" />
			</p>
			<p>
				<input type="hidden" name="action" value="ajax_action" /> 
				<input type="button" value="Submit" id="submit_button" /> 
			</p>
		</form>
	</div>
	<div id="output"></div>';
}
add_shortcode('MCform', 'createMCForm');

Note the hidden field called “ajax_action”, this is the name of the action which sends the Ajax request to the WordPress Ajax API.

The jQuery code to process the Ajax form request

I used this kind of code for several Ajax contact forms in the past. There is one important point I need to mention, you need to use “jQuery(document)” instead of “$(document)” in your code to get it working in WordPress. How the jQuery Ajax functions works is not part of this tutorial.

jQuery(document).ready(function($) {
	$('#submit_button').click(function() { 
		$.ajax({
			type: 'POST',
			url: ajax_object.ajaxurl, 
			data: $('form#myform').serialize(),
			dataType: 'json',
			beforeSend: function() {
				var name = $('#name').val();
				var lname = $('#lname').val();
				var email = $('#email').val();
				
				if (!name || !email) { 
					$('#output').html(ajax_object.errorEmpty);
					return false; 
				}
				emailpat = /^([a-z0-9])+([\.a-z0-9_-])*@([a-z0-9])+(\.[a-z0-9_-]+)+$/i;
				if (!emailpat.test(email)) {
					$('#output').html(ajax_object.errorEmail); 
					return false;
				}
			},
			success: function(response) {
				if (response.status == 'success') {
					$('#formcont').html('');
					
				}
				$('#output').html(response.errmessage);
			}
		});
	});
});

Using this code snippet I do some basic form validation and the “ajax_object” declarations are used for the error messages. These are the objects I’ve defined inside the functions.php file. After the form is processed, we empty the “#formcont” container on success and/or showing an (error) message.

Add this code to a file named “mailchimp.js” and upload the file to the “js” directory inside your theme directory (create the directory if it doesn’t exists). To include the new JavaScript file in your WordPress header you need to add this code BEFORE the code which starts with “wp_localize_script…” to your functions.php file:

wp_enqueue_script( 'ajax-script', plugin_dir_url(__FILE__).'mailchimp.js', array('jquery'), 1.0 ); // jQuery will be included automatically

Using the WordPress Ajax API

Using the function “wp_localize_script()” we’re able to define client side variables inside the WordPress header. We define this way the form’s “action” and two error messages for the form validation process. Add this code to your functions.php file, too.

wp_localize_script( 'ajax-script', 'ajax_object', array( 
				'ajaxurl' => admin_url( 'admin-ajax.php' ),
				'errorEmpty' => __( 'The first name and the e-mail field are required' ),
				'errorEmail' => __( 'The entered e-mail address is not valid.' )
		) 
); 

Register the subscription using the MailChimp API

First I add two actions to the WordPress “system” to include my custom function named “ajax_action_stuff”. Inside the function you need to add the Mailchimp API key and the ID from the mailing list you have created in Mailchimp. Next I check the submitted form values and than we use cURL to send the values to the Mailchimp system. Your Mailchimp URL might be different from mine, the URL depends on how old your account is. Read this information from the API documentation to learn which URL works with your API key.

add_action( 'wp_ajax_ajax_action', 'ajax_action_stuff' ); // ajax for logged in users
add_action( 'wp_ajax_nopriv_ajax_action', 'ajax_action_stuff' ); // ajax for not logged in users

function ajax_action_stuff() {
	$resp['status'] = 'error';
	$resp['errmessage'] = '';
	$apikey = 'your api key';
	$listID = 'your list ID';
	if (!empty($_POST['email']) && !empty($_POST['name'])) {
		
		$name = $_POST['name'];
		$lname = $_POST['lname'];
		$email = $_POST['email'];
		
		$url = sprintf('http://api.mailchimp.com/1.2/?method=listSubscribe&apikey=%s&id=%s&email_address=%s&merge_vars[OPTINIP]=%s&output=json&merge_vars[FNAME]=%s&merge_vars[LNAME]=%s', $apikey, $listID, $email, $_SERVER['REMOTE_ADDR'], $name, $lname);
		$ch = curl_init($url);
		curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
		$data = curl_exec($ch);
		curl_close($ch);
		$arr = json_decode($data, true);
		if ($arr == 1) {
			$resp['errmessage'] = 'Check now your e-mail and confirm your subscription.';
			$resp['status'] = 'success';
		} else {
			switch ($arr['code']) {
				case 214:
				$resp['errmessage'] = 'You are already subscribed.';
				break;
				// check the MailChimp API for more options
				default:
				$resp['errmessage'] = 'Unkown error...';
				break;			
			}
		}
	} else {
		$resp['errmessage'] = 'Missing required fields!';
	}
	header( "Content-Type: application/json" );
	echo json_encode($resp);
	exit;
}

After the data was submitted I use the response to decide which information I need to send back to the web client. There are more error codes, but in my opinion the code 214 (already subscribed) is the most common code. Add more cases with different error codes to the switch statement if you like, find more information about Mailchimp error codes here.

What happens next?

The PHP script will create from the “$resp” array a JSON string which is returned to your Ajax script. This script will output a message and will empty the form container on success. Add the shortcode named “MCform” to your post, widget or theme and don’t forget to add some CSS rules to your stylesheet.

Tutorial code download
We put all the code together and created a plugin for some easy implementation. There is no settings screen, that will say you need to add the API key and list ID right into the plugin file. Download the WordPress plugin here. 

Published in: WordPress Development