Download a list

Download the specified list from your account.


Name Parameter
Data Type Description
Authorization: Header False Required String (Bearer {access token}) Pass the authentication token that was granted when you authorized access.
listid Path False Required String The id of list to be updated {listid} in path above).
count Query false optional String (default="1000", maximum="1000") Number of records to download.
offset Query false Optional String (default="0") Index into the list; where to start downloading.
modbefore Query False Optional String Filter on date "modified before timestamp." *
modafter Query False Optional String Filter on date "modified after timestamp." *
createdbefore Query False Optional String Filter on date "created before timestamp." *
createdafter Query False Optional String Filter on date "created after timestamp." *
fields Query False Optional String (semicolon delimited list) A semicolon ( ; ) delimited list of fields to display in the returned list. Fields provided should be urlencoded. The "_contact_id_" field is always returned.
This parameter is optional. If it is not provided, the whole list will be returned.

The query parameter "datequalifiers" cannot be used in conjunction with this option. However, date modified and created timestamp* data can be added while using this option by specifying the field names "__modified_date" and/or "__created_date" in the list of fields to display.
datequalifiers Query False Optional Boolean true/false If specified as "true", the returned list will include timestamps* for each row denoting the dates created and modified. These columns will be headed with the names "__created_date" and "__modified_date".

This option cannot be specified in conjunction with the query parameter "fields", and can only be appended to a complete (all fields present) list return.
responseformat Query False Optional String Desired response format. Valid values are JSON and CSV with JSON being the default value. If CSV is specified then the first row will be the headers and following rows will be double quoted comma separated values. While JSON is limited to 1,000 list members per API call, CSV can return the entire list even if it is large.

For JSON response format the number of fields is limited to 255. For CSV response format the number of fields is unlimited.

* Note: Unix timestamp, in milliseconds. (timestamp converter:example)


The following request examples use the ID for an example list that is available in every developer account:



A successful request results in an HTTP 200 response with a JSON object like the following. Note that the JSON lists the ID, any offset, the number of rows, and the headers before listing the data:

Code Examples

The java code examples use the java unirest library available at You can also find unirest libraries for node, ruby, php, java, objective c, python, and .net.


Grant Type Password
Grant Type Code
Grant Type Refresh
Account API
Get account information
Create new account user
Delete account users
Delete account user
Get email senders
Fact API
Upload custom events
Get upload custom event status
List API
Get listing of lists
Download a list
Create a new list
Update or merge a list
Get list upload status
Get rejected records from an upload
Delete a list
Delete records from a list
Get hard bounce list
Get spam complaint list
Get Opt-Out List
Update Out-Out List
Get Subscription Opt-Outs by Category
Content API
Get Logo List
Get a logo
Add a logo
Update a logo
Delete a logo
Get header list
Get a header
Add a header
Update a header
Delete a header
Get footer list
Get a footer
Add a new footer
Delete a footer
Update a footer
Get image list
Get an image
Add an image
Replace an image
Delete an image
Get media list
Get media file
Add a media file
Add a media link
Update Media File
Delete a media object
Get form list
Get promotional form URLs
Get page list
Get page
Delete page
Get promotional page URLs
Get list of programs
Reporting API
Get message report
Get message report drilldown
Get message report by time period
Get media report
Get media message report
Get a media view report
Get a media timeline report
Get form report
Get page report
Get spam complaint list
Get hard bounce list
Email Campaign API
Get message list
Send a message
Resend a message
Add new template or draft message
Update template or draft message
Delete a message
Get message report
Get message report drilldown
Get message report by time period
Get message HTML contents
Contact API
Add a contact
Get contact record
Upsert a contact record by email
Update a contact by record ID
Delete a contact
Get contact record ID based on cookie value
Get contact from list based on cookie ID or e-mail
Get contact fact and score data
Get subscription categories
Opt in/Opt out subscription category by email address
Get subscription category opt-ins by email
Opt in/Opt out multiple subscription categories by email address
Get SEO keywords
Get a new SEO report
Frequently Asked Questions