Use Tags with API 3.0

Tags are labels that help organize your contacts. You can use them to bring your own contact structure into Mailchimp and label them using your API key. Tags are highly customizable, so you can create and assign them as you see fit.

Before You Start

  • Review Mailchimp’s basic API calls to make sure you’re comfortable making basic calls.
  • You will need to create a list/audience in your Mailchimp account if you do not 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 are ready to manage contact data.

Identify Contacts

The Mailchimp API 3.0, no longer uses or exposes internal database IDs eid and leid for emails and list/email combinations Instead, we identify contacts by the MD5 hash of the lowercase version of their email address so you can easily predict the API URL of a contact’s data.

For example, to get the MD5 hash of the email address, first convert the address to its lowercase version: The MD5 hash of is 62eeb292278cc15f5817cb78f7790b08.


Below is the list of the available tag endpoints:

  • Create a new tag POST /lists/{list_id}/segments
  • See a contact’s tags GET /lists/{list_id}/members/{subscriber_hash}/tags
  • Bulk add/remove tag contacts POST /lists/{list_id}/segments/{segment_id}
  • Add a tag to a contact POST /lists/{list_id}/segments/{segment_id}/members
  • Remove a tag from a contact DELETE /lists/{list_id}/segments/{segment_id}/members/{subscriber_hash}

Create a New Tag

To create a new tag, use the POST /lists/{list_id}/segments endpoint. Create the tag by passing an empty array in the body without any contact information. An example of the body formatted for JSON is:


View Tags

To view the tags are associated with a contact, you will need the MD5 hash and the GET /lists/{list_id}/members/{subscriber_hash}/tags endpoint.

Here’s an example response:

    "tags": [
            "id": 10297,
            "name": "Influencer",
            "date_added": "2018-07-16 19:49:42"
            "id": 10125,
            "name": "Shops sales",
            "date_added": "2018-07-12 14:53:18"
    "total_items": 2

Manage Tags

After you create tags, you can manage them using API 3.0. Add or delete the tags associated with a contact following the instructions below.

Add Tags to Contacts

To add an existing tag to a contact, you will need the Segment ID, the contact’s email, and the POST /lists/{list_id}/segments/{segment_id}/members endpoint.

Example Body:

	"email_address": ""


An easy way to see the Segment ID assigned to a tag is to send a GET request with the /lists/{list_id}/segments endpoint.

Tag Multiple Contacts in Bulk

To tag multiple contacts in bulk, you will need the Segment ID, the list of contacts you want to tag, and the POST /lists/{list_id}/segments/{segment_id} endpoint.

Delete a Tag

To delete the tags associated with a contact, use the DELETE /lists/{list_id}/segments/{segment_id}/members/{subscriber_hash} endpoint.

Resources and Samples