Create and use tags to categorize a group of contacts.

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:

STEP 2: Add Tags to Contacts

Note: This endpoint will become available in a future release.

Use the POST /activities/add_tagging 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.

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.

Note: Using tags as segment criteria will become available in a future release.

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.

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.

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.

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.

Managing Tags

Use the following V3 API endpoints to manage tags.

POST /contact_tags

Use this method to create a new tag.

GET /contact_tags

Use this method to get details about all tags in your account.

GET /contact_tags/{tag_id}

Use this method to get details about a specific tag.

PUT /contact_tags/{tag_id}

Use this method to update the name of an existing tag.

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.

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.