Using jQuery and the Mailchimp API to get around the “Already Subscribed” error.

A HUGE thanks to Wes Bos without whom I never would have understood this. He is a master at breaking things down and I hope to pay it forward without butchering the steps :)

Mailchimp makes it very easy to get started with email marketing, and everything works pretty flawlessly right out of the box. However there is one serious limitation: a single email address can only be added once to any given list.

Why does this matter?

Say you already have a list of a few hundred subscribers and you’ve started building an online course. You create a landing page about your course, complete with an email capture form so you can let folks know the day you launch.

If you get a fresh new subscriber you’re golden. However if someone already on your list wants to sign up for this new thing, Mailchimp will throw an error message like “Hey you’re already on this list!”

The solution

We are going to create our own optin form. Then we will use a php wrapper for the Mailchimp API and process our form via an ajax call to a custom end-point we will create.

We are also going to add custom merge fields to our form (basically data about our course we can tie to our subscribers) which we can use for segmenting our list.

If all of this sounds like “fhasirckskurjndlfu” to you, don’t worry — it was a nightmare for me too, and I intend on walking you through it step by step.

Will we be doing ALL the things?

My intention here is to explain the process of getting our form’s data back into Mailchimp. I am therefore keeping everything as simple as possible with a flat file structure and minimal code. Also I am not dealing with:

  • Fancy form error handling or confirmation messages
  • Automated responses or Mailchimp automation

There are many tutorials for that stuff.

Ok let’s go!

1. Create a custom form

We’re creating a PDF guide for cats called “5 Steps to Purrrfect Love”. Our goal is to create an optin form so we can let all the cool cats know when our guide is available.

Even though we’re going to create our own custom form, there are a few key pieces of critical code we will need from the embedded Mailchimp forms. The easiest approach is to just copy/paste their code and get rid of what we don’t need.

Make your way to the list you want work on (dashboard -> lists -> your list). From there click on signup forms and then embedded forms.

We will be copying some code from Maichimp’s embedded forms

Uncheck all the options except the required fields and copy the code into A fresh HTML file.

Click to copy the entire code block to your clipboard (you can’t just choose bits and pieces)

The only lines we are concerned with are these:

<label for="mce-EMAIL">Email Address </label>
<input type="email" value="" name="EMAIL" class="required email" id="mce-EMAIL">
<label for="mce-FNAME">First Name </label>
<input type="text" value="" name="FNAME" class="required" id="mce-FNAME">

You will need to include any required fields associated with your list (the email address will be the absolute minimum). In my example I also have first name as a required field. YMMV depending on your list settings. Delete the rest of the code.

From this point you can code your own form. I’m keeping it super simple:

2. Create a custom merge field

We need to add details to our form specific to our guide. This is where custom merge fields in Mailchimp come in.

2.1 Create the merge field for our list

First head to your Mailchimp dashboard. Go to the settings dropdown for your list and select “list fields and merge tags”.

  • Next click on the “Add a Field” button and select “text” as the type.
  • Enter a label for your merge tag and enter the value for your tag (note: it must be in all caps and MC will limit you to 10 characters).
  • Leave required and visible unchecked (this is important to avoid submit errors).

At this point go back to your list and you should see a new column for your field:

2.2 Add the custom merge tag to our form

Let’s add an additional form input for our custom merge tag:

<input type="hidden" value="Yes" name="5PURRRFECT">

What we are doing here is saying: “Anyone who signs up on this form wants to receive emails about this product”.

Note that your value can be whatever you want, however the name must exactly match the tag from your dashboard. Also, we have set this as a hidden field. We just want the data passed along; we don’t need our users to see it.

Our final form should look like this:

3. Download the Mailchimp API wrapper

Emails and API keys are sensitive information, therefore we can’t just process them directly with javascript and risk exposing the data on the front-end. As a work-around we will access the API via a wrapper on the backend.

In this example we will be using PHP and Drew McLellen. The specific file you want is MailChimp.php located here:

Just downloaded the file (without renaming it) and dump it in your project folder.

4. Create the endpoint

Next create a new php file mc-end-point.php and paste in the following code (we will customize it in the next steps):

4.1 Add your API key

Find your profile page in the Mailchimp dashboard and then click on the “extras” tab.

  • Click on the “create new key” button.
  • Copy the key and paste it in the single quotes at this line in your mc-end-point.php file :
$MailChimp = new MailChimp('YOUR-API-KEY'); // put your API key here

4.2 Add your list ID

On the List dashboard, head to the settings dropdown and select “list name and defaults”. You will find the list ID on the right.

Copy it to your clipboard and paste it inside the single quotes at this line in your mc-end-point.php file:

$list = 'YOUR-LIST-ID'; // put your list ID here

4.3 Add your merge fields

Next we want to pass along the values for our merge fields. We have a variable $mergefields set up for this in our mc-end-point.php file.

We can reference our form’s markup to get what we need. In this case we want the first name and our product field.

Change this snippet from

$mergeFields = array(


$mergeFields = array(

Note that you can add as many or as few merge fields as you like in each of your forms. Just remember to create them in your list dashboard!

5. Use jQuery to pass the data to our end-point

For the sake of making the demo as clear as possible, I am adding the jQuery directly to the body of html file, and I am heavily commenting the code.

Also as a quick check-in, here is the current, simple document structure:

5.1 Add the jQuery

Add this chunk of code before the closing <body> tag in your html document (where your form is).

Make sure to replace the path to the endpoint file with your own!

// Replace the path to your own endpoint!$.getJSON('http://localhost:8888/cool-cats-optin/mc-end-point.php', formData ,function(data) {

6. Let’s try it out!

If all goes well you should be able to fill in the form and get a “Thanks” alert. Then go check into your Mailchimp dashboard to see new subscribers added. They should also get a “yes” tied to the new tag!

Remember, the whole point was to allow cats already subscribed to your list to also sign up and just have their info updated, right? If we fill the form out with an email already in our list ( it will just update that user’s data with a value of “Yes” for our product:

7. Create a segment based on our custom merge field.

Mailchimp allows you to create segments based on data tied to your lists and subscribers in order to send out targeted campaigns. As a last step, we will use the data from our 5PURRRFECT custom merge field to create such a segment.

From the “Manage Subscribers” drop-down, select “Segments”.

Click on “New Segment”, set your conditions, and save it:

All done, whew!

Hopefully this has been helpful and you will now be able to work around Mailchimp’s annoying limitation regarding a single subscriber filling out multiple optin forms. If you have any other questions you can find me @luclemo



Independent Front-end Designer | Educator | Kayaker @luclemo |

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Lucas Lemonnier

Lucas Lemonnier

Independent Front-end Designer | Educator | Kayaker @luclemo |