Organize Contacts with Tags
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
An audience in your Mailchimp account
The Audience/List ID for that audience
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
{
"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.