MailChimp form using jQuery ajax

NOTE: This posting was originally written for MailChimp API version 1 and MailChimp will stop support for API versions 1 & 2 at the end of 2016.

UPDATE:  Click HERE to view the updated solution using MailChimp API v3.0


I created a simple HTML page for a dynamic MailChimp sign-up form using jQuery ajax. This means that your users can signup for your MailChimp list without leaving your page. Better than that, they will signup without a page refresh, as the jQuery and `ajax()` will dynamically update the page with the response from the MailChimp API server. This means that you can use jQuery animations to fade out the form, display an animated spinner while the user waits, and then fade in the message. With jQuery, and a little imagination, the possibilities are endless.

The PHP files are “hidden” in the background where the user never sees them yet the jQuery ajax can still access them invisibly. Even when your website is static HTML, without any PHP, this solution will work so that nobody will ever see a `.php` in their URL.

1) Download the PHP 5 jQuery example here…

2) Follow the directions in the Readme file by adding your API key and List ID to the `store-address.php` file at the proper locations.

3) You may also want to collect the user’s first & last name and/or other form information. You’ll have to add an array to the `store-address.php` file using the corresponding Merge Variables.

Here is what my `store-address.php` file looks like where I also gather the first name, last name, and email type:

    function storeAddress(){
    	require_once('MCAPI.class.php');  // same directory as store-address.php

    	// grab an API Key from
    	$api = new MCAPI('123456789-us2');

        // Merge Variables
    	$merge_vars = Array( 
    		'EMAIL' => $_GET['email'],
        	'FNAME' => $_GET['fname'], 
        	'LNAME' => $_GET['lname']
    	// grab your List's Unique Id by going to
    	// Click the "settings" link for the list - the Unique Id is at the bottom of that page. 
    	$list_id = "123456a";
    	if($api->listSubscribe($list_id, $_GET['email'], $merge_vars , $_GET['emailtype']) === true) {
    		// It worked!	
    		return 'Success!&nbsp; Check your inbox or spam folder for a message containing a confirmation link.';
    	} else {
    		// An error ocurred, return error message	
    		return '<b>Error:</b>&nbsp; ' . $api->errorMessage;

    // If being called via ajax, autorun the function
    if($_GET['ajax']){ echo storeAddress(); }

4) Create your HTML/CSS/jQuery form. It is not required to be on a PHP page.

Here is what my `index.html` file looks like. This code is contained between the `<body></body>` tags:

<form id="signup" action="index.html" method="get">
        <input type="hidden" name="ajax" value="true" />
        First Name: <input type="text" name="fname" />
        Last Name: <input type="text" name="lname" />
        email Address (required): <input type="text" name="email" />
        HTML: <input type="radio" name="emailtype" value="html" checked="checked" />
        Text: <input type="radio" name="emailtype" value="text" />
        <input type="submit" />
<div id="message"></div>

<script src="jquery.min.js" type="text/javascript"></script>
<script type="text/javascript">
    $(document).ready(function() {
        $('#signup').submit(function() {
            $("#message").html("<span class='error'>Adding your email address...</span>");
                url: 'inc/store-address.php', // proper url to your "store-address.php" file
                data: $('#signup').serialize(),
                success: function(msg) {
            return false;

Required pieces…

`index.html` constructed as above or similar. With jQuery, the appearance and options are endless.

`store-address.php` file downloaded as part of PHP examples on Mailchimp site and modified with your API KEY and LIST ID. You need to add your other optional fields to the array.

`MCAPI.class.php` file downloaded from Mailchimp site (version 1.3 for PHP 5). Place it in the same directory as your `store-address.php` file or you must update the url path within `store-address.php` file to find it.

WordPress tags and categories cannot share slugs

There is a very frustrating bug in WordPress that seems to not allow you to use the same slug for both a Category and a Tag.

When creating Categories or Tags, WordPress will automatically append a `-2` to any duplicate slug. In other words, if you try to create a Category and a Tag both named “Computers”, WordPress will make sure one of the slugs is spelled `computers-2`. If you then try to edit the slug for the Category or Tag to remove the `-2`, it will not allow it and give you an error.

Since Categories and Tags are two different things, duplication of a slug should not be an issue. If you Google search “wordpress category and tag slug”, you will find a lot of complaining going back a very long time, and a lot of closed support threads at without any official responses.

However, there is a workaround to this issue.


– desired Category and Tag name: “Computers”
– desired slug: `computers`

1. Make sure no Categories or Tags already exist with a slug spelled `computers`.

2. Create the “Computer” Category first and if you leave the “Slug” field blank, WordPress will automatically create the slug `computers`. You can also type “computers” into the Slug field when creating this Category. The important thing here is to make sure your slug is spelled correctly before moving on.

3. Create the “Computer” Tag. At this step, you must manually create the slug `computers` by typing “computers” into the “Slug” field. Otherwise, if you leave the “Slug” field blank, WordPress will create the slug automatically, it will be spelled `computers-2`, and WordPress will not allow you to remove the `-2` through edits. You would have to delete the Tag entirely and start over.

That’s it. There are other workarounds to this issue which involve creating Tags on the fly when the corresponding Category already exists. However, the steps I’ve outlined above are the simplest. Good luck!