Follow

Create List

The Create List command allows you to define and create a new Normal list to add Subscribers.  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]

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk