list

Create, update, or get information about any list. Update the criteria of an existing Smart List.

To download or upload email addresses use the job call.

Endpoint URL: https://api.sailthru.com/list


GET a list

Get basic information about a list. If no list name or ID is specified, this call will return a list of your lists with each list’s type specified–smart or normal. “Normal” is the API’s term for a natural list. Learn about natural vs. smart lists here. The response can also be filtered to show only lists marked as primary (using “primary”:1).

Examples

By Name or ID

By Name:

{
   "list":"100List"
}

By ID:

{
   "list_id":"53df0861dd52b83c368c784b"
}

Response:

{
   "list_id" : "53df0861dd52b83c368c784b",
   "list" : "100List",
   "create_time" : "Tue, 03 Jun 2014 14:15:09 -0400",
   "send_time" : "Wed, 21 Jan 2015 15:01:11 -0500",
   "count" : 100,
   "type" : "normal",
   "primary" : true
}

By Name or ID & Return Vars

By Name:

{
   "list":"100List",
   "fields":{"vars":1}
}

By ID:

{
   "list_id":"53df0861dd52b83c368c784b",
   "fields":{"vars":1}
}

Response:

{
   "list_id" : "53df0861dd52b83c368c784b",
   "list" : "100List",
   "create_time" : "Tue, 03 Jun 2014 14:15:09 -0400",
   "send_time" : "Wed, 21 Jan 2015 15:01:11 -0500",
   "count" : 100,
   "type" : "normal",
   "primary" : true
   "vars" : {
   "color" : "blue"
   }
}

Required Parameters

Parameter Description Example
list the name of the list my-list

Alternatively, you can use list_id:

Parameter Description Example
list_id calls a list by id number {"list_id" : "53df0861dd52b83c368c784b"}

Optional Parameters

Parameter Description Example
fields The fields to return. Only needed to return variables. {"list":"Master List","fields":{"vars":1}}

POST to Create or Modify List

For Smart Lists, you can create or update the criteria used to include users in the list via the query parameter. (See User Queries for Job and List for further details and examples.)

To add/remove users from a Natural List, use the job call.

The return value will include a create_time if the referenced list is not new, and was modified by the call.

Note that your account is allowed a maximum of 2000 lists.

Examples

Natural List

Example Call:

{
   "list":"natural test list",
   "primary":1,
   "vars":{"color":"blue"},
   "public_name":"natural test list public name",
   "type":"natural"
}

Example Response:

{
   "list" : "natural test list",
   "type" : "normal",
   "primary" : 1,
   "public_name" : "natural test list public name",
   "vars" : {
   "color" : "blue"
   },
   "list_id" : "5840769f83ba8848008b458e"
}

Smart List

Example Call:

{
   "list":"smart test list",
   "primary":1,
   "vars":{"color":"blue"},
   "public_name":"smart test list public name",
   "type":"smart",
   "query":
   {
      "source_list":"main",
      "criteria":["match"],
      "field":["color"],
      "value":["blue"]
   }
}

Example Response:

{
   "list" : "smart test list 1",
   "type" : "smart",
   "description" : "All primary list users: 'color' is 'blue'",
   "primary" : 1,
   "public_name" : "smart test list public name",
   "vars" : {
   "color" : "blue"
   },
   "list_id" : "584086cd83ba8845008b458e"
}

Required Parameters

Parameter Description Example
list the name of the list my-list

Optional Parameters

Parameter Description Example
primary set to 1 to make the list a primary list, 0 to make the list non-primary 1
vars Any number of arbitrary variables to store for later use {"color":"blue","category":"men"}
public_name assign a public name for a list that will be displayed to subscribers (i.e. on an optout page) My New List
query Use the API Query format to create the underlying query criteria for a Smart List
"query":
{
"source_list":".primary",
"criteria":["match"],
"field":["color"],
"value":["blue"]
}
type set to smartto make the list a Smart List, or normal for a normal list smart

 

DELETE a List

Example

Example Call:

{
   "list":"smart test list"
}

Example Response:

{
   "list" : "smart test list",
   "ok" : true
}

Required Parameters

Parameter Description Example
list the name of the list my-list

Error Codes

HTTP Status Error Code Error Message Notes Request type
400 2 Missing required parameter: list PUT/DELETE
200 99 Primary parameter must be 0 or 1 For example”primary”:2 POST
200 99 The total number of vars cannot exceed 20 POST
200 99 The variable key name cannot start with a number – ‘1color’ var names cannot start with an number POST
200 99 The variable key must be combination of numbers/letters and underscore – ‘[varName!]’ Invalid character used in var name POST
200 99 The key name is too long ‘abcdefg123…’, maximum is 32 Var name exceeds length limit POST
200 99 The value for key ‘[VarKeyName]’ is too long ‘[varValueName]’. Maximum is 140 Var value exceeds length limit POST
200 99 You may only track up to 50 primary lists. Primary list copy/generation attempted when 50 already exist. POST
400 99 Error: Copy list only supports smart list “copy_list” parameter used on natural list POST
400 99 Error: New list name already exists When using”copy_list”  POST
403 99 This feature is no longer supported, please use the /job API to make List Rename calls “rename” parameter was used POST
403 99 Cannot modify list type List type can’t be swapped between natural and smart lists. POST
403 99 Cannot modify list query on natural list “query” was specified on a natural list POST
403 99 This list is currently associated with a campaign that is sending or about to send. Please wait for the campaign to finish sending. List has active blasts POST
400 99 List name: [ListName] failed validation No valid characters in list name GET/POST
404 15 Unknown list: [ListName] GET/DELETE
200 99 List [ListName] has a pending job and can’t be deleted at this time Job API job in progress that is reliant on the list. DELETE
200 99 List ‘foo’ cannot be deleted at this time. It is being used in Site Personalization Manager by the following section(s): bar DELETE
200 99 List ‘foo’ cannot be deleted at this time. It is being used by the following recurring campaign(s): DELETE
Top