How to delete contacts and restore deleted contacts.

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.

Learn more.

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

Try it!

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

Try it!

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.