The Create List command allows you to define and create a new Normal list to add Contacts. The command allows you to specify several components of a list, such as From and Reply To addresses. The Create List command includes two options: createlist and excreatelist. The only difference is that excreatelist returns the List ID after the list has been successfully created. More advanced List properties must be managed through the web interface or the WebServices API where available.
The Create List command requires the following arguments: Command, Realm, Password, and List Name.
api_web?r=myrealm&p=mypass&c=createlist&list_name=My+List
The command is ‘createlist', the realm is ‘myrealm’ and the password is ‘mypass’. The new, empty list will be named ‘My List’.
Create List only supports Normal Lists and does not allow creation of List Definitions or Lists of type Super, Seed, or Smart.
Example
Using createlist with all commands and arguments (please note the command is wrapped for display purposes only):
api_web?r=myrealm&p=mypass&c=createlist&list_name=mylist&description=test_list&template_id=42&from="Descriptive"%20<from%40domain.com>&reply_to="Descriptive"%20<reply%40domain.com>&errors_to=mailbox??EMAIL_REF??%40response.domain.com&track_clicks=1&track_opens=1&folder_id=5&list_unsubscribe_flag=1&list_unsubscribe_email=mailto%3aunsub@mydomain.com&list_unsubscribe_http=http%3a%2f%2fwww.mydomain.com%2funsub
Successful results return:
SUCCESS
Using excreatelist with all commands and arguments (please note the command is wrapped for display purposes only):
api_web?r=myrealm&p=mypass&c=createlist&list_name=mylist&description=test_list&template_id=42&from="Descriptive"%20<from%40domain.com>&reply_to="Descriptive"%20<reply%40domain.com>&errors_to=mailbox??EMAIL_REF??%40response.domain.com&track_clicks=1&track_opens=1&folder_id=5&list_unsubscribe_flag=1&list_unsubscribe_email=mailto%3aunsub@mydomain.com&list_unsubscribe_http=http%3a%2f%2fwww.mydomain.com%2funsub
Successful results return, where ‘66’ is the ID of the new list:
SUCCESS: 66
Results
The Create List commands output either a SUCCESS or FAILURE message.
Success
The command success message returns the SUCCESS message. The id of the new list is shown for excreatelist only. The result format is:
SUCCESS
or
SUCCESS: [list_id]
Failure
The command will fail if a list with the same name already exists or invalid data is defined. The result format is:
FAILURE: [Reason]
Arguments
The command supports the following arguments:
|
Name |
Req? |
Description |
Argument |
|
Command |
Yes |
Defines the command to use. |
cmd=[createlist, excreatelist] c=[createlist, excreatelist] |
|
Realm |
Yes |
Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match. |
realm=[realm_name] r=[realm_name] |
|
Password |
Yes |
Authentication code for API access. This is required, and the command will fail if the realm and password do not match. |
pwd=[password] p=[password] |
|
List Name |
Yes |
Name of the list to create. To include spaces, use + or %20 to avoid possible issues with spaces in a URL. |
list_name=[list_name] |
|
Description |
|
A short description of the list. |
description=[text] |
|
Template |
|
The default template associated with the List. You can obtain a list of template IDs using the command show_templates. |
template_id=[template_id] |
|
From Address |
|
Email address the message appears to be sent from. Though not required to create a list, a From address should 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. |
from=[email_address] from=["Decorative"%20 <email_address>] |
|
Reply To Address |
|
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. |
reply_to=[email_address] reply_to=["Decorative"%20 <email_address>] |
|
Bounce Address |
|
Mailbox to catch bounce replies. If not defined, no bounce tracking will occur. |
errors_to=[bounce_address] |
| Track Click-Throughs | If you want to track click-throughs from your messages, set this option to ‘1’. |
track_clicks=[0,1] DEFAULT==0 |
|
| Track Opens | If you want to track opens from your messages, set this option to ‘1’. |
track_opens=[0,1] DEFAULT==0 |
|
| Folder | Identifier of the Folder to associate the List for organization. Default folder is 0, or Unfiled. | folder_id=[folder_id] | |
| List Unsubscribe |
List-Unsubscribe is an integrated third-party tool to include an Unsubscribe link in the email message headers of some email clients, such as Gmail. If enabled, you can set one or both methods. Email must be prepended with 'mailto:', and the URL must include http:// or https://. It is recommended to encode the special characters, such as:
|
list_unsubscribe_flag=[0,1] DEFAULT == 0 list_unsubscribe_email=mailto%3a[email] |