Deleted Contacts
Deleting a contact removes any list memberships for the contact and does not remove the contact from a user’s account. Deleted contacts do not count against the number of active contacts for an account. Deleted contacts have a status=deleted
, a deleted_at
time stamp, and are not members of any lists. Deleted contacts are not unsubscribed. You can un-delete deleted contacts by adding them to one or more lists.
View Deleted Contacts
Use the status
query parameter with GET calls to the contacts collection endpoint to view all deleted contacts:
GET https://api.cc.email/v3/contacts?status=deleted&include=list_memberships
You can also use the status
query parameter with the value all
to return all contacts including deleted contacts. By default, GET /contacts
does not return deleted contacts.
Endpoint Requirements
User privileges: contacts:read
Authorization scopes: contact_data
Here’s a payload of a deleted contact; a deleted contact will have a deleted_at
entry, and it does not have any list_memberships
:
{
"contact_id": "{contact_id}",
"email_address": {
"address": "example@example.com",
"permission_to_send": "implicit",
"created_at": "2013-04-01T15:07:07-04:00",
"updated_at": "2015-03-17T12:01:31-04:00",
"opt_in_source": "Account",
"opt_in_date": "2015-03-17T11:13:28-04:00",
"confirm_status": "off"
},
"first_name": "John",
"last_name": "Byrd",
"update_source": "Account",
"create_source": "Account",
"created_at": "2013-04-01T15:07:07-04:00",
"updated_at": "2018-01-25T05:40:30-05:00",
"deleted_at": "2015-03-17",
"list_memberships": []
}
Try it! in the API Reference
Delete a Contact
Use the individual contact endpoint and the DELETE method to delete contacts one at a time. The DELETE Contact method removes all list memberships for the contact. In this example, the contact was a member of 2 lists. Performing a GET call to retrieve this contact with include=list_memberships
shows the contact is not a member of any lists.
DELETE https://api.cc.email/v3/contacts/{contact_id}
Endpoint Requirements
User privileges: contacts:write
Authorization scopes: contact_data
<?php
$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contacts/{contact_id}');
$request->setMethod(HTTP_METH_DELETE);
$request->setHeaders(array(
'Cache-Control' => 'no-cache',
'Authorization' => 'Bearer {access_token}',
'Content-Type' => 'application/json',
'Accept' => 'application/json'
));
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
curl -X DELETE \
https://api.cc.email/v3/contacts/{contact_id} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://api.cc.email/v3/contacts/{contact_id}")
.delete(null)
.addHeader("Accept", "application/json")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {access_token}")
.addHeader("Cache-Control", "no-cache")
.build();
Response response = client.newCall(request).execute();
Response
204 No Content
Delete Many Contacts
Use the contact delete bulk activity endpoint to delete tens, hundreds or thousands of contacts in a single API call. Learn more.
POST /activities/contact_delete
Endpoint Requirements
User privileges: contacts:write
Authorization scopes: contact_data
Restore a Deleted Contact
To restore a deleted contact, use the PUT /contacts/{contact_id}
endpoint to add the contact to one or more contact lists and specify the update_source
as Account
(required).
PUT https://api.cc.email/v3/contacts/{contact_id}
Endpoint Requirements
User privileges: contacts:write
Authorization scopes: contact_data
<?php
$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contacts/{contact_id}');
$request->setMethod(HTTP_METH_PUT);
$request->setHeaders(array(
'Cache-Control' => 'no-cache',
'Authorization' => 'Bearer {access_token}',
'Content-Type' => 'application/json',
'Accept' => 'application/json'
));
$request->setBody('{
"first_name": "John",
"last_name": "Byrd",
"email_address": {
"address": "example@example.com",
"permission_to_send": "explicit"
},
"update_source": "Account",
"list_memberships":["{list_id1}","{list_id2}"]
}');
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
curl -X PUT \
https://api.cc.email/v3/contacts/{contact_id} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"first_name": "John",
"last_name": "Byrd",
"email_address": {
"address": "example@example.com",
"permission_to_send": "explicit"
},
"update_source": "Account",
"list_memberships":["{list_id1}","{list_id2}"]
}'
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \n \"first_name\": \"John\",\n \"last_name\": \"Byrd\",\n \"email_address\": {\n \"address\": \"example@example.com\",\n \"permission_to_send\": \"explicit\"\n },\n \"update_source\": \"Account\",\n \"list_memberships\":[\"{list_id1}\",\"{list_id2}\"]\n}");
Request request = new Request.Builder()
.url("https://api.cc.email/v3/contacts/{contact_id}")
.put(body)
.addHeader("Accept", "application/json")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {access_token}")
.addHeader("Cache-Control", "no-cache")
.build();
Response response = client.newCall(request).execute();
Response
{
"contact_id": "{contact_id}",
"first_name": "John",
"last_name": "Byrd",
"update_source": "Account",
"create_source": "Account",
"created_at": "2013-04-01T15:07:07-04:00",
"updated_at": "2018-02-20T16:47:40-05:00",
"email_address": {
"address": "example@example.com",
"permission_to_send": "implicit",
"created_at": "2013-04-01T15:07:07-04:00",
"updated_at": "2018-02-20T16:47:40-05:00",
"opt_in_source": "Account",
"opt_in_date": "2015-03-17T11:13:28-04:00",
"confirm_status": "off"
}
}
Restore Multiple Deleted Contacts
You can restore multiple contacts in a single API call by using the Bulk Activity Add Contacts to Lists endpoint to add all the contacts to one or more lists. Learn more.