Bulk Activities - Remove Contacts Multipart Endpoint

Use this endpoint to create an asynchronous background job that removes contacts from one or more contact lists by importing a list of contacts in binary form using the multipart content-type. The supported file types are:

  • txt
  • csv
  • xls

Methods:

Click a method to view its documentation

POST

DescriptionTOP

Privileges required: contacts:write

You can remove contacts from one or more contact lists using a .txt or .csv file that contains only the email addresses of the contacts to be removed. You need to use an HTTP multipart request in a POST to this endpoint. The multipart request contains three parameters: file_name, lists, and data, defined in the Structure section below.

Limitations

The size of the payload (import file) must be less than 4 megabytes. Also, you can remove a maximum of 20,000 contacts in a single POST. The activity will fail if the payload is greater than 4 MBs or if it includes more than 20,000 contacts.

The data file must contain only email addresses. Do not include any other data columns in the file, and do not include any labels or other non-email content in the file.

Example Multipart Encoded POST

The following is an example multipart encoded post written in Java that removes contacts from contact lists 4 and 6 by importing a file (contacts.txt) containing only the email addresses of the contacts to remove:

final HttpClient httpclient = new DefaultHttpClient();
   final HttpPost httppost = new HttpPost("https://api.constantcontact.com/v2/activities/removefromlists");

   httppost.addHeader("Authorization", "Bearer 5e35af38-7b63-47cac-b484-20c4ff4d09c8");
   httppost.addHeader("Accept", ”application/json”);
   httppost.addHeader("content-type", "multipart/form-data");

   final File fileToUse = new File("/path_to_file/contacts.txt");   //e.g. /temp/contact.txt
   final FileBody data = new FileBody(fileToUse);
   final String listIds = "1", "4";
   final StringBody lists = new StringBody(listIds);
   final StringBody fileName = new StringBody(fileToUse.getName());
   final MultipartEntity reqEntity = new MultipartEntity();
   reqEntity.addPart("file_name", fileName);
   reqEntity.addPart("lists", lists);
   reqEntity.addPart("data", data);

   httppost.setEntity(reqEntity);

   final HttpResponse response = httpclient.execute(httppost);
   final HttpEntity resEntity = response.getEntity();

   EntityUtils.consume(resEntity);

  httpclient.getConnectionManager().shutdown();
}

Activity Status

To see the status of an activity, make a GET call to the URI returned in the response's location header:

Location: https://api.constantcontact.com/v2/activities/<activity_id>

Poll this URI to monitor the activity status until the status is either COMPLETE or ERROR, indicating that the activity has completed processing. The response structure for this GET call is detailed here.

See also: Summary Activity Reports API 

POST: https://api.constantcontact.com/v2/activities/removefromlists

name

type

default

description

api_key

query

REQUIRED; The API key for the application

Response CodesTOP

code

description

201

Request was successful, and is queued for processing

400

Bad Request; Error in validating a contact

401

Authentication failure

429

We cannot complete your request because you have too many requests in progress.

500

Internal server error occurred

StructureTOP

property

type(max length)

description

data

string

REQUIRED. Part of the multipart requestbody, it's the data contained in a .txt or .csv file being uploaded. The file must contain only email addresses.

file_name

string

REQUIRED. Part of the multipart requestbody, it's the name of the .txt or .csv file that contains the contact email addresses to remove from the lists

lists

string

REQUIRED. Part of the multipart requestbody, this is a comma separated list of contact list Ids specifying the contact lists from which the contacts are to be removed

Response StructureTOP

property

type(max length)

description

contact_count

string

Displays the number of valid email addresses that were in the request payload only. It does not indicate the number of contacts that were removed from lists. (Read Only)

error_count

string

This is always 0 for REMOVE_CONTACT_FROM_LISTS activity type. (Read Only)

id

string

Unique ID for the activity (Read Only)

type

string

REMOVE_CONTACT_FROM_LISTS (Read Only)

Example ResponseTOP

{
"id": "a07e1il97jehddh1z8x",
"type": "REMOVE_CONTACTS_FROM_LISTS",
"error_count": 0,
"contact_count": 2
}