Remove Contacts from Lists Bulk Activity

Use the /activities/remove_list_memberships endpoint to quickly remove large numbers of contacts from one or more existing lists. This endpoint allows you to specify the contacts to remove from lists in one of three mutually exclusive ways:

• by contact_id - you can specify up to 500 individual contacts by contact_id
• by list_id - all contacts that are members of up to 50 lists
• all_active_contacts - all active contacts on the user’s account

Contacts can be removed from as many as 50 existing lists in the user’s account in one POST call to this endpoint.

JSON Request Payload

The JSON request payload consists of two main components:

• source - identifies the contacts to remove from lists
• list_ids - identifies the lists from which the contacts will be removed

Source - Identifying Contacts

The source object in the request payload can contain one of three mutually exclusive properties identifying the contacts to remove from lists:

• contact_ids - an array that can contain up to 500 individual contact_id values
• list_ids - an array of up to 50 individual list_id values. All contacts that are members of these “source” lists will be removed from the “destination” lists.
• all_active_contacts - a boolean that, when set to “true”, the request will remove all active contacts in the user’s account from the “destination” lists.

Use only one of these options.

Destination Lists

The list_ids array (outside of the source object) can contain up to 50 list_id values. These are the “destination” lists from which the contacts will be removed.

Example Request

POST https://api.cc.email/v3/activities/remove_list_memberships

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/activities/remove_list_memberships');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access_token}',
  'Cache-Control' => 'no-cache'
));

$request->setBody('{
  "source": {
    "list_ids": [
      "{list_id_1}",
      "{list_id_2}",
      "{list_id_3}"
    ],
    "tag_ids": [
      "{tag_id_1}",
      "{tag_id_2}",
      "{tag_id_3}"
    ],
    "all_active_contacts": true,
    "contact_ids": [
      "{contact_id_1}",
      "{contact_id_2}",
      "{contact_id_3}"
    ]
  },
  "list_ids": [
    "{list_id_1}",
    "{list_id_2}",
    "{list_id_3}"
  ]
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

curl -X POST \
  https://api.cc.email/v3/activities/remove_list_memberships \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Cache-Control: no-cache' \
  -d '{
  "source": {
    "list_ids": [
      "{list_id_1}",
      "{list_id_2}",
      "{list_id_3}"
    ],
    "tag_ids": [
      "{tag_id_1}",
      "{tag_id_2}",
      "{tag_id_3}"
    ],
    "all_active_contacts": true,
    "contact_ids": [
      "{contact_id_1}",
      "{contact_id_2}",
      "{contact_id_3}"
    ]
  },
  "list_ids": [
    "{list_id_1}",
    "{list_id_2}",
    "{list_id_3}"
    ]
}'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"source\": {\n\t\t\"list_ids\": [\n\t\t\t\"{list_id_1}\",\n\t\t\t\"{list_id_2}\",\n\t\t\t\"{list_id_3}\"\n\t\t],\n\t\t\"tag_ids\": [\n\t\t\t\"{tag_id_1}\",\n\t\t\t\"{tag_id_2}\",\n\t\t\t\"{tag_id_3}\"\n    \t],\n    \t\"all_active_contacts\": true,\n    \t\"contact_ids\": [\n    \t\t\"{contact_id_1}\",\n    \t\t\"{contact_id_2}\",\n    \t\t\"{contact_id_3}\"\n    \t\t]\n\t},\n\t\"list_ids\": [\n\t\t\"{list_id_1}\",\n\t\t\"{list_id_2}\",\n\t\t\"{list_id_3}\"\n\t\t]\n}");
Request request = new Request.Builder()
  .url("https://api.cc.email/v3/activities/remove_list_memberships")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer {access_token}")
  .addHeader("Cache-Control", "no-cache")
  .build();

Response response = client.newCall(request).execute();

Example Response

{
  "activity_id": "{actvity_id}",
  "state": "initialized",
  "started_at": "completed",
  "completed_at": "2016-01-23T13:48:44.108Z",
  "created_at": "2016-01-23T13:48:44.108Z",
  "updated_at": "2016-01-23T13:48:44.108Z",
  "percent_done": 75,
  "activity_errors": [
    "Message describing the error condition."
  ],
  "status": {
    "items_total_count": 2200,
    "items_completed_count": 652,
    "list_count": 3
  },
  "_links": {
    "self": {
      "href": "/v3/activities/{actvity_id}"
    }
  }
}

Checking the Activity Status for Job Complete

Check on the activity status by calling the activity status endpoint using the activity_id provided in the _links section of the response. The activity_id is located in the href link. To retrieve the status, make the following GET call:

GET https://api.cc.email/v3/activities/{activity_id}

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

Try it!