Manage Subscribers with the MailChimp API

Most people use the MailChimp API to manage subscriber data. You can subscribe and unsubscribe individuals and sync metadata with your systems. In this guide, you’ll learn the basics of how to manage list subscribers via the API.

Before You Start

Here are some things to know before you manage subscribers with the API.

  • Before you begin, review MailChimp’s basic API calls, and make sure you’re comfortable making those basic calls.
  • You’ll need to create a list in your MailChimp account if you don’t have one already, and find the List ID. This guide uses a sample List ID (9e67587f52), so be sure to substitute your own List ID when you’re ready to manage subscriber data.

Identify Subscribers

In previous versions of the API, we exposed internal database IDs eid and leid for emails and list/email combinations. In API 3.0, we no longer use or expose either of these IDs. Instead, we identify your subscribers by the MD5 hash of the lowercase version of their email address so you can easily predict the API URL of a subscriber’s data.

For example, to get the MD5 hash of the email address Urist.McVankab@freddiesjokes.com, first convert the address to its lowercase version: urist.mcvankab@freddiesjokes.com. The MD5 hash of urist.mcvankab@freddiesjokes.com is 62eeb292278cc15f5817cb78f7790b08.

Check Subscription Status

To see if an email address subscribed to your list, you’ll need your List ID, the email address, and its MD5 hash.

For the address, urist.mcvankab@freddiesjokes.com, you’d make a GET request to /3.0/lists/9e67587f52/members/62eeb292278cc15f5817cb78f7790b08.

If the call returns a 404 response, the subscriber isn’t on your list. They may have been deleted, or they were never on the list at all.

If the call returns a 200 response, check the status field. You’ll see one of these labels in the status field.

  • subscribed This address is on the list and ready to receive email. You can only send campaigns to ‘subscribed’ addresses.
  • unsubscribed This address used to be on the list but isn’t anymore.
  • pending This address requested to be added with double-opt-in but hasn’t confirmed their subscription yet.
  • cleaned This address bounced and has been removed from the list.

Subscribe an Address

To add someone to your list, send a POST request to the List Members endpoint: /3.0/lists/9e67587f52/members/. The request body should be a JSON object that has the member information you want to add, with status and any other required list fields.

{
    "email_address": "urist.mcvankab@freddiesjokes.com",
    "status": "subscribed",
    "merge_fields": {
        "FNAME": "Urist",
        "LNAME": "McVankab"
    }
}

You’ll receive errors if the address is already on your list, or if any required merge_fields are missing. Find the full list of fields available in the List Member Schema.

Subscriber Status

To add a subscriber, you must include the subscriber’s status in your JSON object.

  • Use subscribed to add an address right away.
  • Use pending to send a confirmation email.
  • Use unsubscribed or cleaned to archive unused addresses.

The unsubscribed option is useful if you import addresses from another service. When you add subscribers to the unsubscribed or cleaned status groups, you’ll have a record of the subscriber, and we’ll prevent sends to that address in the future. That’s ideal for inactive or unsubscribed addresses, which can increase spam complaints if they’re accidentally added as subscribed.

Update an Address

Use a PATCH request to the address’s endpoint to update an address’s metadata. The body can be a JSON object with only the data you want to change.

For example, to unsubscribe urist.mcvankab@freddiesjokes.com, make a PATCH request to /3.0/lists/9e67587f52/members/62eeb292278cc15f5817cb78f7790b08 with this JSON object as the body:

{
    "status": "unsubscribed"
}

Delete an Address

We don’t typically recommend deleting addresses from your list because it’s permanent and cannot be undone. It’s better to change its status to unsubscribed or cleaned.

If you want to delete an address anyway, along with all its statistics, make a DELETE call to that address’s endpoint.

Create or Update an Address

For jobs that regularly sync data from one system to MailChimp, you may need to create a new address or update an existing subscriber’s address. Depending on data volume, there are two approaches you could take for address creation and updates.

  • If data is static and grows slowly, update the address first, and only try to create a new address when the update fails.

  • For large imports, we recommend that you create addresses first and only update if the creation fails.