Mailchimp Developer LogoMailchimp Developer Wordmark
Skip navigation

Mailchimp Marketing API

Organize Contacts with Tags

For Marketers

At a glance

Tags are labels that help organize your contacts. While segments help filter an audience based on things like when a contact subscribed or how often they engage with campaigns, you can use tags to bring your own email targeting and organization strategy into Mailchimp.

You could use tags to:

  • Structure campaigns for specific audiences, tagging contacts with terms like “Holiday Send” or “Influencer” 

  • Directly map tags from your CRM onto tags in your Mailchimp audience 

  • Translate behaviors—for example, a contact who’s spent $1,000 in your store—into tags that can be used in future campaigns

In this guide, we’re going to create a new “Influencer” tag to track and target our most influential customers. We’ll walk through how to programmatically tag contacts as influencers, view all of our influencers, remove the influencer tag from a contact whose sway has (sadly) diminished, and continue to manage tags through all of our potential use cases.

What you’ll need

Label a contact with a tag

We want to tag Urist McVankab, whose star has been rising recently, as an influencer. 

To add the Influencer tag, make this request using your List ID and the MD5 hash of Urist McVankab’s email address:

Label a contact with a tag

dc="YOUR_DC"
apikey="YOUR_API_KEY"
listid="YOUR_LIST_ID"
subscriber_email="urist.mcvankab@example.com"
subscriber_hash="$(echo -n "$subscriber_email" | md5sum | cut -d’ ‘ -f1)"
# use below for OS X
# subscriber_hash="$(md5 -s "$subscriber_email" | cut -d' ' -f4)"

curl -s --request POST \
--url "https://${dc}.api.mailchimp.com/3.0/lists/${listid}/members/${subscriber_hash}/tags" \
--user "foo:${apikey}" --include \
--data '{"tags": [{"name": "Influencer", "status": "active"}]}'

Note: The Marketing API identifies contacts by the MD5 hash of the lowercase version of their email address so you don't need to send their email over the internet when you retrieve or update a contact’s data.

View a contact’s tags

Now we want to check out all of Urist’s tags. Again, using the MD5 hash of his email address, make the following request:

View a contact’s tags

dc=”YOUR_DC”
apikey=”YOUR_API_KEY”
listid=”YOUR_LIST_ID”
subscriber_email=”urist.mcvankab@example.com”
subscriber_hash=”$(echo -n “$subscriber_email” | md5sum | cut -d’ ‘ -f1)”
# use below for OS X
# subscriber_hash="$(md5 -s "$subscriber_email" | cut -d' ' -f4)"

curl -s --request GET \
--url "https://${dc}.api.mailchimp.com/3.0/lists/${listid}/members/${subscriber_hash}/tags" \
--user "foo:${apikey}" | jq -r .

The full response might look something like this:

Urist the Influencer

JSON
{
    "tags": [
        {
            "id": 10297,
            "name": "Influencer",
            "date_added": "2018-07-16 19:49:42"
        },
        {
            "id": 10125,
            "name": "Tech",
            "date_added": "2018-07-12 14:53:18"
        }
    ],
    "total_items": 2
}

You can see Urist is tagged with our Influencer tag, along with a Tech tag, which he must have been labeled with previously.

Remove a tag

Time passes; influence fades. We’ve decided to remove Urist’s Influencer tag. Doing so is simple: make the same request you did when you added the tag, but this time, set the status to inactive.

Remove a tag

dc=”YOUR_DC”
apikey=”YOUR_API_KEY”
listid=”YOUR_LIST_ID”
subscriber_email=”urist.mcvankab@example.com”
subscriber_hash=”$(echo -n “$subscriber_email” | md5sum | cut -d’ ‘ -f1)”
# use below for OS X
# subscriber_hash="$(md5 -s "$subscriber_email" | cut -d' ' -f4)"

curl -s --request POST \
--url "https://${dc}.api.mailchimp.com/3.0/lists/${listid}/members/${subscriber_hash}/tags" \
--user "foo:${apikey}" --include \
--data '{"tags": [{"name": "Influencer", "status": "inactive"}]}'

Note: Only explicitly referenced tags will be updated using this endpoint; that is, if your contact has been tagged several times and you want to remove a tag, you have to explicitly name the tag and set a status of inactive. (You cannot send an empty array of tags in an effort to remove all of your contact’s tags.)

Bulk tagging

Forget about Urist—now we have a batch of influencers to tag. 

We can bulk tag contacts in two ways. First, if you’re using a tag that already exists, you’ll need the Tag ID for that tag. When we viewed Urist’s tags above, we saw that the ID for the Influencer tag was 10297, so we can use that to make the following request:

Add bulk tags

dc=”YOUR_DC”
apikey=”YOUR_API_KEY”
listid=”YOUR_LIST_ID”
tagid=”YOUR_TAG_ID”

body() {
  cat <<EOT
{
  “members_to_add”: [
    "dolly.parton@example.com",
    "rihanna@example.com"
  ]
}
EOT
}

count=”$(curl -s --request POST \
--url "https://${dc}.api.mailchimp.com/3.0/lists/${listid}/segments/${tagid}" \
--user "foo:${apikey}" --include \
--data “$(body)” | jq -r ‘.total_added’)”

echo “Successfully tagged ${count} contacts”

The payload requires an array of members you want to add to your tag. To untag a batch of contacts, make the the same request, but instead include members you want to remove from your tag:

Remove bulk tags

dc=”YOUR_DC”
apikey=”YOUR_API_KEY”
listid=”YOUR_LIST_ID”
tagid=”YOUR_TAG_ID”

body() {
  cat <<EOT
{
  “members_to_remove”: [
    "john.smith@example.com",
    "brad.hudson@example.com"
  ]
}
EOT
}

count=”$(curl -s --request POST \
--url "https://${dc}.api.mailchimp.com/3.0/lists/${listid}/segments/${tagid}" \
--user "foo:${apikey}" --include \
--data “$(body)” | jq -r ‘.total_removed’)”

echo “Successfully untagged ${count} contacts”

If, instead, we wanted to bulk add users to a completely new tag—say, “MegaInfluencer”—we can create the tag and add contacts to it in one quick request:

New bulk tags

dc=”YOUR_DC”
apikey=”YOUR_API_KEY”
listid=”YOUR_LIST_ID”

body() {
  cat <<EOT
{
  “name”: “MegaInfluencer”,
  “static_segment”: [
    "dolly.parton@example.com",
    "rihanna@example.com"
  ]
}
EOT
}

tagid=”$(curl -s --request POST \
--url "https://${dc}.api.mailchimp.com/3.0/lists/${listid}/segments/" \
--user "foo:${apikey}" --include \
--data “$(body)” | jq -r ‘.id’)”

echo “Tag successfully created! Your tag id is ${tagid}”

The data for our tag includes a name (“Influencer”) and the static_segment array. If we only wanted to create a tag but add no contacts to it, we could have passed an empty array. For more details, see the Add segment endpoint.

Note: You may have noticed that the API call above references segments, but this guide is about tags. This is an implementation detail within the API that can be confusing. Previously tags were referred to as “static segments;” now they are referred to as tags. When you create a tag using the structure above, you’ll see the results as tags and not segments when you view your lists in your Mailchimp account.

More resources