REST API Lists
The Rest API supports the ability to manage Lists. The Rest API URI for Lists resource is in the format:
https://[siteurl]/rest/lists
Commands
API Commands for List management include:
Name | HTTP Method | Endpoint | Description |
POST | /rest/lists | Create a List | |
PUT | /rest/lists/{listId} | Update specific List | |
DELETE | /rest/lists/{listId} | Delete specific List | |
GET | /rest/lists | Get details for all Lists | |
GET | /rest/lists/{listId} | Get details for specific List | |
GET | /rest/lists?listName={listName} | Get details for specific List | |
GET | /rest/lists/{listId}/subscribers | Get all Contacts in List | |
GET | /rest/lists/{listId}/subscribers?{subscriber query fields} | Get specific Contact in List |
List Property Data Fields
The following data fields may be set and viewed. You will notice that there are properties which are available within the UI that are not available in the API. These must be edited within the UI only. For more details about the fields, see List Properties:
Field Name | Methods | Description | Type | Example |
List Name | POST, PUT, GET | Unique Name of the List. | String | "listName": "[listName]" |
From Address | POST, PUT, GET | Email address the message appears to be sent from. A From address must always be defined before sending a list. It can be a simple email address, or can include a decorative portion in addition to the email address, in the format: "Decorative"%20 <email_address> | String | "listFromAddress": "[fromEmail]" |
Reply To Address | POST, PUT, GET | Email address to send replies. A Reply To address should always be defined before sending messages from a list. It can be a simple email address, or can include a decorative portion in addition to the email address, in the format: "Decorative"%20 <email_address> | String | "listReplyToAddress": "[replyToEmail]" |
Bounce Address | POST, PUT, GET | Mailbox to catch bounce replies. If not defined, no bounce tracking will occur. | String | "listMailFromAddress": "[bounceEmail]" |
Description | POST, PUT, GET | Short description to identify the purpose of the list. | String | "listDescription": "[listDescription]" |
Admin Email | POST, PUT, GET | Customer email address to receive notifications when Campaigns have been sent or failed. | String | "listAdminEmail": "[email]" |
Created Date | GET | Date the List was created. | Date | "listCreatedDate": "Mar 22, 2016 4:05:11 PM" |
Updated Date | GET | Last date that changes were made and saved to the List. | Date | "listUpdatedDate": "Mar 23, 2016 12:45:04 PM" |
Parent List ID | POST, GET | Identifier for the List Definition from which the Normal List was created. | Integer | "parentTemplateId": [listDefinitionId] |
List Definition Flag | POST, GET | Flag to identify if used as a List Definition, a reusable template from which new Lists can be created. 0: Not a List Definition | Boolean | "isTemplate": 0 |
Courtesy Template: Subscribe | POST, PUT, GET | Identifier for the optional Template to send when a subscription is completed and a courtesy message is enabled. | Integer | "listSubscribeEmailTemplateId": [templateId] |
Courtesy Template: Unsubscribe | POST, PUT, GET | Identifier for the optional Template to send when a subscription is completed and a courtesy message is enabled. | Integer | "listUnsubscribeEmailTemplateId": [templateId] |
Confirmation Required: Subscribe | POST, PUT, GET | Require contacts to confirm their subscription. | Boolean | "listConfirmSubs": true, false |
Courtesy Subscribe | POST, PUT, GET | Send a courtesy email message after a contact chooses to subscribe via a specific Link or Form. | Boolean | "listSendCourtesySubsEmail": true, false |
Courtesy Unsubscribe | POST, PUT, GET | Send a courtesy email message after a contact chooses to unsubscribe via a specific Link or Form. | Boolean | "listSendCourtesyUnsubsEmail": true, false |
Subscribe Landing Page | POST, PUT, GET | URL to landing page after a contact chooses to subscribe via a specific Link or Form. | String | "listConfirmationSubGoto": "[URL]" |
Unsubscribe Landing Page | POST, PUT, GET | URL to landing page after a contact chooses to unsubscribe via a specific Link or Form. | String | "listConfirmationUnsubGoto": "[URL]" |
Track Opens | POST, PUT, GET | Track when a contact opens/reads a message. | Boolean | "listTrackingReadEnabled": true, false |
Track Clicks | POST, PUT, GET | Track when a contact clicks a link in a message. | Boolean | "listTrackingClickthroughEnabled": true, false |
Sticky Campaign Flag | POST, PUT, GET | Aggregate all tracking from any Campaign sent over time via this List into a single Campaign report. | Boolean | "listUseStickyCampaign": 0 |
Set Data Macro | POST, PUT, GET | MISSING | Integer | "listSetDataMacroId": [setDataMacroId] |
FTAF From Address | POST, PUT, GET | Use the List's From address instead of the contact's email address for forwarded messages. | Boolean: 0,1 | "ftafUseListFromAddress": 1 |
Virtual MTA | POST, PUT, GET | The IP through which campaigns are published. | Integer | "vmtaId": [vmtaId] |
Base URL | POST, PUT, GET | Custom tracking replacement URL identifier. | Integer | "baseUrlId": [baseUrlId] |
List-Unsubscribe Flag | POST, PUT, GET | Include an Unsubscribe link in the header of any message sent using this List.
| Boolean | "unsubscribeHeaderEnabled": true, false |
Default Automation Campaign | POST, PUT, GET | Automation Campaign to add all new Contacts. | Integer | "defaultLifecycleCampaignId": [lcCampaignId] |
Add to Automation Campaign | POST, PUT, GET | Automatically add all new Contacts to a Marketing Automation Campaign. | Boolean: false,true | "defaultLifecycle": true, false |
List-Unsubscribe: Alternate URL | POST, PUT, GET | If List-Unsubscribe is true, optional alternate URL to include in message header as Unsubscribe link. | String | "unsubHeaderHttpValue": "[URL]" |
List-Unsubscribe: Mailto | POST, PUT, GET | If List-Unsubscribe is true, optional Email address to send an opt-out request in the format: | String | "unsubHeaderEmailValue": "mailto:[email]" |
List ID | GET | Unique Identifier of the List. | Integer | "listId": [listId] |
Realm ID | GET | Identifier of the Realm in which the List exists. | Integer | "listRealmId": [realmId] |
Default Template | POST, PUT, GET | Optional default template associated with the list. You may change the template when you deploy a campaign. | Integer | "listTemplateId": [templateId] |
Folder | POST, PUT, GET | Folder in which the List resides for sorting and storage. | Integer | "listFolderId": [folderId] |
Segmentation Rule | GET | For use with Smart Lists only. **Removed in v16.15 | Integer | "listSegmentationRuleId" : [segmentationId] |
List Type | GET | 0: Normal A List Definition also appears as type: 0. | Integer | "type": 0,1,2,3 |
Contact Count Total | GET | Total number of Contacts subscribed to the List. Super Lists and List Definitions always show a count of 0. | Integer | "subscriberCountTotal": 0 |
Contact Count Plain Text | GET | Total number of Contacts subscribed to receive Plain Text formatted content. Super Lists and List Definitions always show a count of 0. | Integer | "subscriberCountPlain": 0 |
Contact Count HTML | GET | Total number of Contacts subscribed to receive HTML formatted content. Super Lists and List Definitions always show a count of 0. | Integer | "subscriberCountHtml": 0 |
Contact Count RSS | GET | Total number of Contacts subscribed to RSS feed. This feature is deprecated, and no longer in use. Removed in v11.16.0 | Integer | "subscriberCountRss": 0 |
Contact Count MIME | GET | Total number of Contacts subscribed to receive MIME formatted content. Super Lists and List Definitions always show a count of 0. | Integer | "subscriberCountMime": 0 |
Skip | GET | Parameter to retrieve next set of results. See Pagination for more details. | Integer | "skip": 0 |
Max | GET | Max is not in use. | Integer | "max": 0 |