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"
}