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 |
| Create List | POST | /rest/lists | Create a List |
| Update List | PUT | /rest/lists/{listId} | Update specific List |
| Delete List | DELETE | /rest/lists/{listId} | Delete specific List |
| Get All Lists | GET | /rest/lists | Get details for all Lists |
| Get List by ID | GET | /rest/lists/{listId} | Get details for specific List |
| Get List by Name | GET | /rest/lists?listName={listName} | Get details for specific List |
| Get All Subscribers in List | GET | /rest/lists/{listId}/subscribers | Get all Subscribers in List |
| Get Specific Subscriber in List | GET | /rest/lists/{listId}/subscribers?{subscriber query fields} | Get specific Subscriber 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 subscribers to confirm their subscription. |
Boolean |
"listConfirmSubs": true, false |
|
Courtesy Subscribe |
POST, PUT, GET |
Send a courtesy email message after a subscriber 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 subscriber 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 subscriber chooses to subscribe via a specific Link or Form. |
String |
"listConfirmationSubGoto": "[URL]" |
|
Unsubscribe Landing Page |
POST, PUT, GET |
URL to landing page after a subscriber chooses to unsubscribe via a specific Link or Form. |
String |
"listConfirmationUnsubGoto": "[URL]" |
|
Track Opens |
POST, PUT, GET |
Track when a subscriber opens/reads a message. |
Boolean |
"listTrackingReadEnabled": true, false |
|
Track Clicks |
POST, PUT, GET |
Track when a subscriber 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 subscriber'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 Subscribers. |
Integer |
"defaultLifecycleCampaignId": [lcCampaignId] |
|
Add to Automation Campaign |
POST, PUT, GET |
Automatically add all new Subscribers 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: mailto:mailbox@domain.com |
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. |
Integer |
"listSegmentationRuleId" : [segmentationId] |
|
List Type |
GET |
0: Normal A List Definition also appears as type: 0. |
Integer |
"type": 0,1,2,3 |
|
Subscriber Count Total |
GET |
Total number of Subscribers subscribed to the List. Smart Lists, Super Lists, and List Definitions always show a count of 0. |
Integer |
"subscriberCountTotal": 0 |
|
Subscriber Count Plain Text |
GET |
Total number of Subscribers subscribed to receive Plain Text formatted content. Smart Lists, Super Lists, and List Definitions always show a count of 0. |
Integer |
"subscriberCountPlain": 0 |
|
Subscriber Count HTML |
GET |
Total number of Subscribers subscribed to receive HTML formatted content. Smart Lists, Super Lists, and List Definitions always show a count of 0. |
Integer |
"subscriberCountHtml": 0 |
|
Subscriber Count RSS |
GET |
Total number of Subscribers subscribed to RSS feed. This feature is deprecated, and no longer in use. Removed in v11.16.0 |
Integer |
"subscriberCountRss": 0 |
|
Subscriber Count MIME |
GET |
Total number of Subscribers subscribed to receive MIME formatted content. Smart Lists, 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 |
Comments