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:

Copy

{
   "list":"100List"}

By ID:

Copy

{
   "list_id":"53df0861dd52b83c368c784b"}

Response:

Copy

{
   "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
}

GET a list with vars

Example call:

Copy

{ "list": "ExampleList",
"fields": {
"vars": 1}}

Response:

Copy

{
    "list_id" : "6012e7bb43e509395b4e8222",
    "list" : "ExampleList",
    "create_time" : "Thu, 28 Jan 2021 10:35:07 -0600",
    "send_time" : "Wed, 16 Mar 2022 09:38:03 -0500",
    "count" : 11,
    "type" : "normal",
    "primary" : true,
    "vars" : {
        "list_var" : "success"    },
    "public_name" : "ExampleList"}

Get All Lists

Copy

{}

Response:

Copy

{
    "lists" : [
        {
            "list_id" : "58e68f1115dd96816a8b4ab0",
            "name" : "!! bar/foo",
            "email_count" : 0,
            "valid_count" : 0,
            "create_time" : "Thu, 06 Apr 2017 14:55:13 -0400",
            "type" : "smart"        }
    ]

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"}`

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.

You cannot use a dollar sign ($) in list names. 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:

Copy

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

Example Response:

Copy

{
   "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:

Copy

{
   "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:

Copy

{
   "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 `smart`to make the list a Smart List, or `normal` for a normal list	`smart`

DELETE a List

Example

Example Call:

Copy

{
   "list":"smart test list"}

Example Response:

Copy

{
   "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
400	99	Invalid JSON provided		POST