What are Tags?
Tags let you easily categorize and group contacts for the purpose of sending targeted messages without having to add contacts to new contact lists. The information used to determine which tags to create is often collected from surveys, membership registration, and sign-up forms. For example, you might create tags to identify groups of contacts that are volunteers, share interests, are loyalty card members, or share job roles (CFO, CEO, Purchaser, Human Resources).
How are Tags Used?
Some of the common ways to use tags include:
- Follow up with non-openers.
- Thank loyal customers.
- Target contacts based in location.
- Target contacts based on topics.
For example:
Last month you sent an email campaign promoting all upcoming concert events to all contacts that are members of two contact lists and that have the loyal fans tag assigned. An upcoming concert is a week away and it is not sold out. To increase ticket sales, you email a special discount offer to only those contacts that are loyal fans and that are not tagged as confirmed attendees.
How are Tags Different from Contact Lists?
- Tags apply directly to contacts, regardless of which lists the contact is a member.
- Tags allow you to keep track of your contacts interests and other relevant information which helps you to further refine and target the right contacts for a particular campaign message.
- If a contact changes list preferences or un-subscribes from a list, the tag information is saved.
- Tags, unlike list names, are not visible to contacts.
Authorization Requirements
To use the tags feature, you must have the Account Owner or Account Manager user role. The required endpoint privileges and scopes are as follows:
POST
, PUT
, and DELETE
:
User privileges: contacts:write
Authorization scopes: contact_data
GET
:
User privileges: contacts:lists:read
Authorization scopes: contact_data
Getting Started
Your account can have up to 500 tags. Tag names must be:
- Unique.
- At least one character in length and not more than 255 characters.
- Tag names are alphanumeric, can include spaces, and common keyboard symbols with the exception of
<
and>
.
To get started using tags, complete the steps that follow.
STEP 1: Create New Tags
Use the POST /contact_tags
endpoint to create a new tag by specifying a unique tag name (name
) in the request body and optionally the source used (tag_source
) to identify the contacts to tag.
For example:
{
"name": "loyal fans",
"tag_source": "ESTY"
}
The response body returns the tag name (name
) and the ID that uniquely identifies the tag (tag_id
) and optionally, the source (tag_source
) used to identify which contacts to tag. It also returns timestamps (in ISO format) showing when the tag was created (created_at
) and last updated (updated_at
). For example:
{
"tag_id": "d938260a-af1e-11e9-a540-fa163e595123",
"name": "Josie Girl 2020",
"tag_source": "ESTY",
"created_at": "2019-07-25T16:57:43-04:00",
"updated_at": "2019-07-25T16:57:43-04:00"
}
Related topics:
-
Learn More about using this endpoint.
STEP 2: Add Tags to Contacts
Use the POST /activities/contacts_taggings_add
endpoint to create a new tagging activity used to identify and tag contacts that meet your tagging criteria by specifying one or more of the following filtering methods:
tag_ids
: Tags to apply to contacts.contact_ids
: Specific contacts to tag (they can be a member on any contact list).-
list_ids
: Contacts that are members on one or more lists. You can also identify a subset of contacts to tag on lists by specifying additional filtering criteria such as contact properties and/or list criteria to exclude or include.Related topics:
-
Learn More about using this endpoint.
-
STEP 3: Send an Email Campaign to Tagged Contacts
To send an email campaign activity to tagged contacts, complete the following tasks:
Create a new segment.
Use the POST /segments
endpoint to create a new tag-based segment by choosing which tags to include or exclude in the segment criteria. Save and use the resulting segment_id
in the task that follows.
-
Learn More about using this endpoint.
Add the segment to an email campaign activity.
Use the PUT /emails/activities/{campaign_activity_id}
endpoint and in the request body segment_ids
array, specify the segment (segment_id
) to use when sending the email campaign activity. You can only include one segment_id
. You cannot specify both a segment_id
and a list_id
.
When an email campaign activity is sent to a segment, Constant Contact uses the segment_criteria
to get refreshed results to identify the contacts that currently meet the segment criteria.
-
Learn More about scheduling and sending an email campaign.
Schedule the email campaign activity to be sent.
Use the POST /emails/activities/{campaign_activity_id}/schedules
endpoint to schedule the email campaign activity to be sent.
-
Learn More about using this endpoint.
Use the POST /emails/activities/{campaign_activity_id}/tests
endpoint to send a test email to specific email addresses. Test emails allow you to verify how the email campaign activity will look before you send it to contacts.
-
Learn More about using this endpoint.
Managing Tags
Use the following V3 API endpoints to manage tags.
POST /contact_tags
Use this method to create a new tag.
-
Learn More about using this endpoint.
GET /contact_tags
Use this method to get details about all tags in your account.
-
Learn More about using this endpoint.
GET /contact_tags/{tag_id}
Use this method to get details about a specific tag.
-
Learn More about using this endpoint.
PUT /contact_tags/{tag_id}
Use this method to update the name of an existing tag.
-
Learn More about using this endpoint.
DELETE /contact_tags/{tag_id}
Use this method to delete a tag and remove the tag from all tagged contacts.
Note: The endpoint will be available in an upcoming release.
-
Learn More about using this endpoint.
Tags Terminology
The following term(s) and definition(s) apply to the contact tags feature:
- Tags: Used to categorize and group contacts that are members on one or more contact lists for the purpose of sending targeted messages. Tags do not require you to create new contact lists.