How to Use Tags with API 3.0

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

Before You Start

Here are some things to know before you begin the process.

  • Review Mailchimp’s basic API calls to 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 API 3.0, we no longer use or expose internal database IDs eid and leid for emails and list/email combinations 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, first convert the address to its lowercase version: The MD5 hash of is 62eeb292278cc15f5817cb78f7790b08.


Use these tags 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 New Tags

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 subscriber information. An example of the body formatted for JSON would be:


View Tags

To view which tags are associated with a contact, you will need the subscriber 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 by using API 3.0. Add or delete the tags associated with a contact by using these specific endpoints.

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.

Bulk Tag Contacts

To bulk tag contacts, 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 Tags

If you want to delete the tags associated with the subscriber, use the DELETE /lists/{list_id}/segments/{segment_id}/members/{subscriber_hash} endpoint.

Resources and Samples