MailChimp form using API v3.0 and jQuery ajax

As per notification at the top of this page, all prior versions of the API will not be supported after 2016.

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 know PHP is being used in the background.

1) Download a PHP wrapper that supports API v3.0. As of this writing, there is nothing official listed in the latest MailChimp docs that supports v3.0, but several are listed on GitHub, so I selected this one.

2) Create the following PHP file, store-address.php, using your own API key and list ID, and then place it in the same directory as the wrapper from step one. Remember to follow the documentation for your wrapper, but they all seem fairly similar to this.

3) Create your HTML/CSS/JavaScript(jQuery) form (It is not required to be on a PHP page, and the visitor will never see that PHP is being used in the background.)

The response is in JSON so you’ll have to handle it correctly.

Here is what my index.html file looks like:

When CodeIgniter’s CSRF Protection breaks your Ajax

CSRF stands for “Cross Site Request Forgery” and if you’re using forms on your site, you’ll probably want to protect yourself and users against this kind of attack.

You just finished your latest PHP project using the CodeIgniter framework and decide to enable the CSRF protection option in your config.php file.

Enabling it within config.php is not enough. You also need to use the form helper form_open() function to construct the form’s HTML markup. This function constructs the form so that it contains a <input type="hidden"> element containing the CSRF token value. If the submitted form data is missing this token, it will not submit.

Now CSRF is working but you discover that your jQuery ajax requests are all suddenly failing with a type 500 server error. This is a direct result of activating the CSRF Protection option in CodeIgniter. As just explained, the submitted form data must contain the CSRF token, but it’s missing from your ajax requests.

The solution is simple. You need to make sure that your ajax requests simulate a regular form submission by including the CSRF token value within the submitted data.

There are two types of solutions:

Solution #1:

This only works if your ajax requests occur when a form is already constructed on the page, such as when doing remote validation to check to see if a password or username already exists.

You’ll need to copy the value from the hidden field called csrf_token (the name is exactly as per your $config['csrf_token_name'] option setting) and send this along with your ajax request.

Solution #2:

This works for all ajax requests, even when you do not have a form on the page, such as remotely loading some content.

In this case, you can’t get the CSRF token from a hidden field, since there is no form. You must retrieve it from the CSRF cookie. I’m using a jQuery cookie plugin.

Notice how the ajax in both solutions is sending the token with the same name, that’s your name as per your configuration, csrf_token. Only the source of the token value is different… Solution #1 gets the token value from the hidden field, where Solution #2 gets the same token value from the cookie.

You can only use Solution #1 when you have a form on the page constructed with the form_open() function. However, you can use Solution #2 with or without a form, in all cases.

NOTES:

I have CodeIgniter v2.1.4 and by default, the $config['csrf_token_name'] option is set to csrf_test_name. This mismatch might get a little confusing, but you can use whatever naming convention you wish. In my solution above, I changed it to csrf_token.

  • To retrieve the current token from the hidden input, use the name assigned to the $config['csrf_token_name'] option.
  • To retrieve the current token from the cookie, use the name assigned to the $config['csrf_cookie_name'] option.

No matter how you retrieve the token value, the important thing to remember is to always send the token value along with whatever name you’ve assigned to the $config['csrf_token_name'] option.

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…

apidocs.mailchimp.com/downloads/mcapi-simple-subscribe-jquery.zip

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:

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:

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.