Create List

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: mailto%3aemail@domain.com http%3a%2f%2fwww.domain.com%2fpage This is new in v12.05.0.	list_unsubscribe_flag=[0,1] DEFAULT == 0 list_unsubscribe_email=mailto%3a[email] list_unsubscribe_http=http%3a%2f%2f[url]