Manage Contacts with the Mailchimp API 3.0

In this guide, you’ll learn how to use the Subscribers endpoint in the Mailchimp API 3.0 to create, update, delete, archive, and sync contacts (and associated metadata) in a list/audience.

Before You Start

  • Review Mailchimp’s basic API calls and make sure you are comfortable making those calls.
  • You’ll need to know the List ID associated with the list/audience you want to work with. To locate the List ID, refer to Find Your List ID for instructions. Note that the examples in this guide use a sample List ID (e.g., 9e67587f52), so be sure to substitute your own List ID where appropriate.

Identify a Contact

In previous versions of the API, the internal database IDs (eid and leid) for emails and list/email combinations were exposed. Mailchimp API 3.0 no longer uses either of these IDs. Instead, the MD5 hash of the lowercase version of the contact’s email address is used. This allows you to easily predict the API URL of the contact’s data.

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

Check a Contact’s Subscription Status

To verify that a contact is subscribed to a list/audience, you’ll need the List ID, the email address, and the MD5 hash.

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

If the call returns a 404 response, the contact is not subscribed to the list/audience.

If the call returns a 200 response, check the status field. One of the following labels will display.

  • subscribed The contact is already subscribed to the list/audience and can receive campaigns. Note that campaigns can only be sent to ‘subscribed’ contacts.
  • unsubscribed The contact is no longer subscribed to the list/audience.
  • pending This contact requested to be added the list/audience with double-opt-in, but has not yet confirmed their subscription.
  • cleaned This contact bounced and was removed from the list/audience.

Add a Contact to a List/Audience

To add a contact to a list/audience, send a POST request to the List Members endpoint: /3.0/lists/9e67587f52/members/. The request body should be a JSON object that contains the 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 get errors if the contact is already subscribed to the list/audience, or if any required merge_fields are missing. The full list of fields available in the List Member Schema.

Contact Status

To add a contact, you must include the status in your JSON object:

  • Use subscribed to add a contact.
  • Use pending to send a confirmation email.
  • Use unsubscribed or cleaned to archive unused contacts.

The unsubscribed option is useful if you import contacts from another service. When you add contacts to the unsubscribed or cleaned status groups, you’ll have a record of the contact, but future messages will not be sent. That is the ideal method for inactive or unsubscribed contacts to prevent an increase in spam complaints if they are accidentally added as subscribed.

Update a Contact

Use a PATCH request to the Members endpoint to update a contact’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 a Contact

We don’t typically recommend deleting contacts because it is permanent and cannot be undone. It is better to change the status to unsubscribed or cleaned.

If you want to delete a contact anyway, along with all the history and statistics, make a DELETE call to Members endpoint.

Create or Update a Contact

For jobs that regularly sync data from a system to Mailchimp, you may need to create or update a contact. Depending on data volume, there are two approaches you could take for contact creation and updates. * If data is static and grows slowly, update the contact first, and only try to create a new contact when the update fails. * For large imports, we recommend that you create addresses first and only update if the creation fails.