API: Rest Create List

The Create List command allows you to define a new List to add Contacts or create a List Definition that can be used as a template for future lists created via the UI. The command allows you to specify several properties of a list, such as From and Reply To addresses. See REST API List Overview for a table of List properties available to POST.

POST /lists

https://[siteurl]/rest/lists

Request Body Parameters

The Create List command requires the following in the Posted JSON in order to create a Normal List:

List Name: "listName": "[listName]"
List Is Template: "isTemplate": false
List From Address: "listFromAddress": "[fromEmail]"

All other POST-able fields are optional, and can be found in the Data Fields table in Rest API List Overview.

To create a reusable List Definition, which is used in the UI, you must set "isTemplate" to true:

List Is Template: "isTemplate": true

While you can create a List Definition, you cannot create a List from a Definition via the REST API. Create List also does not support creation of Seed Lists, or Super Lists at this time.

Request Body Example

Using Create List with all arguments, line breaks in JSON for readability:

CODE

curl --request POST \ 
--url 'https://mail.mydomain.com/rest/lists' \ 
--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \ 
--header 'content-type: application/json' \ 
--header 'accept: application/vnd.whatcounts-v1+json' \ 
--data '{ 
"listName": "myList", 
"listFromAddress": "from@mydomain.com", 
"listReplyToAddress": "replyto@mydomain.com", 
"listMailFromAddress": "bounce??EMAIL_REF??@mail.mydomain.com", 
"listDescription": "My Subscriber List", 
"listAdminEmail": "myemail@mydomain.com", 
"parentTemplateId": 0, 
"isTemplate": false, 
"listSubscribeEmailTemplateId": 0, 
"listUnsubscribeEmailTemplateId": 0, 
"listConfirmSubs": false, 
"listSendCourtesySubsEmail": false, 
"listSendCourtesyUnsubsEmail": false, 
"listConfirmationSubGoto": "", 
"listConfirmationUnsubGoto": "", 
"listTrackingReadEnabled": true, 
"listTrackingClickthroughEnabled": true, 
"listUseStickyCampaign": false, 
"ftafUseListFromAddress": false, 
"vmtaId": 0, 
"baseUrlId": 0, 
"unsubscribeHeaderEnabled": false, 
"defaultLifecycleCampaignId": 0, 
"defaultLifecycle": false, 
"unsubHeaderHttpValue": "", 
"unsubHeaderEmailValue": "", 
"listTemplateId": 0, 
"listFolderId": 0 }' \ 
--include

Response Body

The response returns all API available List Properties in JSON format. Based on the example above, the response returns:

CODE

HTTP/1.1 200 OK
Server: serverName
Content-Type: application/json
Content-Length: 926
Link: <https://mail.mydomain.com/rest/lists>;
Date: Fri, 17 Jun 2016 12:54:44 GMT
{
"listFromAddress": "from@mydomain.com"
"listReplyToAddress": "replyto@mydomain.com"
"listMailFromAddress": "bounce??EMAIL_REF??@mail.mydomain.com"
"listDescription": "My Subscriber List"
"listAdminEmail": "myemail@mydomain.com"
"listCreatedDate": "Jun 17, 2016 12:54:44 PM"
"listUpdatedDate": "Jun 17, 2016 12:54:44 PM"
"parentTemplateId": 0
"isTemplate": false
"listSubscribeEmailTemplateId": 0
"listUnsubscribeEmailTemplateId": 0
"listConfirmSubs": false
"listSendCourtesySubsEmail": false
"listSendCourtesyUnsubsEmail": false
"listConfirmationSubGoto": ""
"listConfirmationUnsubGoto": ""
"listTrackingReadEnabled": true
"listTrackingClickthroughEnabled": true
"listUseStickyCampaign": false
"ftafUseListFromAddress": false
"vmtaId": 0
"baseUrlId": 0
"unsubscribeHeaderEnabled": false
"defaultLifecycleCampaignId": 0
"defaultLifecycle": false
"unsubHeaderHttpValue": ""
"unsubHeaderEmailValue": ""
"listId": 10
"listRealmId": 1561
"listTemplateId": 0
"type": 0
"listName": "myList"
"listFolderId": 0
"subscriberCountTotal": 0
"subscriberCountPlain": 0
"subscriberCountHtml": 0
"subscriberCountRss": 0
"subscriberCountMime": 0
"skip": 0
"max": 0
}

Error Response

Error Response Codes include both Client Errors (4xx) and Server Errors (5xx). Descriptions of each can be found in Response Codes.

For example, if the required List Name is missing, the error would appear as:

{ "error": "A List Name should be defined. The List Name field must be at least 1 characters long" "status": "Internal Server Error" "statusCode": 500 }