Create a new tag.

Tags allow you to target a subset of your contacts for a particular marketing campaign without having to add them to a new contact list, and unlike contact lists, tag names are not exposed to contacts. For example, your might create a tag to identify contacts that are gold card members or that have donated to a campaign event in the past.

Create a Tag

To create a tag, use the POST /contact_tags method. In the request body you must specify a unique name (name) that identifies the tag and optionally, the source (tag_source) used to identify the contacts to tag.

Tag names must:

  • be unique to avoid returning a 409 error response.
  • consist of at least one character and not more than 255 characters to avoid returning a 400 error response.
  • be alphanumeric, which can include spaces, and common keyboard symbols (with the exception of < and >).

For example:

{
  "name": "Dogs Rule 2020 Donors",
  "tag_source": "JOJO"

}

The response body returns the name and the ID that uniquely identifies the 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": "Dogs Rule 2020 Donor",
     "tag_source": "JOJO",
     "created_at": "2019-07-25T16:57:43-04:00",
     "updated_at": "2019-07-25T16:57:43-04:00"
 }

When you first create a tag, the created_at and edited_at timestamps are identical.

Authorization Requirements

User privileges: contacts:write

Authorization scopes: contact_data

Example POST Tag Requests

POST https://api.cc.email/v3/contact_tags

 <?php
 
 $curl = curl_init();
 
 curl_setopt_array($curl, array(
   CURLOPT_URL => "https://api.cc.email/v3/contact_tags",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "POST",
   CURLOPT_POSTFIELDS =>"{\n  \"name\": \"Dogs Rule 2020 Donors\",\n  \"tag_source\": \"JOJO\"\n\n}",
   CURLOPT_HTTPHEADER => array(
     "Authorization: Bearer {access_token}",
     "Content-Type: application/json"
   ),
 ));
 
 $response = curl_exec($curl);
 
 curl_close($curl);
 echo $response;

curl --location --request POST 'https://api.cc.email/v3/contact_tags' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Dogs Rule 2020 Donor"
  "tag_source": "JOJO"
}'
 OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
 MediaType mediaType = MediaType.parse("application/json");
 RequestBody body = RequestBody.create(mediaType, "{\n  \"name\": \"Dogs Rule 2020 Donors\",\n  \"tag_source\": \"JOJO\"\n\n}");
 Request request = new Request.Builder()
   .url("https://api.cc.email/v3/contact_tags")
   .method("POST", body)
   .addHeader("Authorization", "Bearer {access_token}")
   .addHeader("Content-Type", "application/json")
   .build();
 Response response = client.newCall(request).execute();
 

Response

 {
     "tag_id": "30c97dd0-332e-11eb-923c-fa163e595591",
     "name": "Dogs Rule 2020 Donor",
     "created_at": "2020-11-30T17:05:04Z",
     "updated_at": "2020-11-30T17:05:04Z"
 }

Try it!