Follow

Create List Definition

The Create List Definition command allows you to define and create a new List template to create new Lists from and use in Automation Campaigns.  The command allows you to specify several components of a List Definition, such as From and Reply To addresses.  The command requires the following arguments: Command, Realm, Password, and List Name.

api_web?r=myrealm&p=mypass&c=createlistdefinition&list_name=My+List+Definition

The command is ‘createlistdefinition', the realm is ‘myrealm’ and the password is ‘mypass’.  The new, empty List Definition will be named ‘My List Definition’.

Example

Using createlistdefinition with all commands and arguments (please note the command is wrapped for display purposes only):

api_web?r=myrealm&p=mypass&c=createlistdefinition&list_name=My+Full+Definition&template_id=42&acct_pro_id=76&labels=226,227,228&from=%22My+From%22%20%3Cfrom@mydomain.com%3E&reply_to_address=%22My+Reply%22%20%3Creply@mydomain.com%3E&errors_to_address=bounce@mydomain.com&description=My+List+Definition&folder_id=26&admin_email=admin@mydomain.com&subscribe_confirmation_flag=1&subscribe_confirmation_from_address=confirm@mydomain.com&subscribe_confirmation_template_id=84&subscribe_confirmation_format=99&subscribe_courtesy_flag=1&subscribe_courtesy_from_address=courtesy@mydomain.com&subscribe_courtesy_template_id=85&subscribe_courtesy_format=99&unsubscribe_courtesy_flag=1&unsubscribe_courtesy_from_address=uncourtesy@mydomain.com&unsubscribe_courtesy_template_id=86&unsubscribe_courtesy_format=99&default_automation_flag=1&default_automation_campaign_id=722&subscribe_landing_page_url=http%3A%2F%2Fwww.mydomain.com&unsubscribe_landing_page_url=http%3A%2F%2Fwww.mydomain.com&tracking_opens_flag=1&tracking_clicks_flag=1&base_url_id=204&vmta=132&set_data_macro_id=4&ftaf_custom_form_url=http%3A%2F%2Fwww.mydomain.com/ftafcustomform.html&ftaf_envelope_url=http%3A%2F%2Fwww.mydomain.com/ftafenvelope.html&ftaf_landing_page_url=http%3A%2F%2Fwww.mydomain.com/ftaflanding.html&ftaf_error_landing_page_url=http%3A%2F%2Fwww.mydomain.com/ftaferror.html&ftaf_allow_anon_flag=1&ftaf_user_list_from_flag=1&dedupe_on_send_flag=1&workflow_flag=1&workflow_email_addresses=workflow@mydomain.com&list_unsubscribe_flag=1&list_unsubscribe_http=http%3A%2F%2Fwww.mydomain.com/unsub&list_unsubscribe_email=mailto:unsub@mydomain.com&sticky_campaign_flag=1&sync_flag=1&sync_open=13&sync_click=14&sync_opt_in=13&sync_opt_out=14&sync_soft=13&sync_hard=14&sync_complaint=13&sync_send=14

Successful results return, where ‘676’ is the ID of the new list definition:

SUCCESS: 676

Results

The Create List Definition commands output either a SUCCESS or FAILURE message. 

Success

The command success message returns the SUCCESS message followed by the new list definition ID.  The result format is: 

SUCCESS: [list_id]

Failure

The command will fail if a list definition with the same name already exists, name is missing, email addresses are not formatted correctly, or invalid data is defined.  The result format is:

FAILURE: [Reason]

Errors include:

FAILURE: There is no name supplied for the List Definition, which is a required field for this command.
FAILURE: The Subscribe Confirmation Format provided is not valid. Acceptable values are 0, 1, 2, 99.
FAILURE: When the Default Automation Flag is true, at least one Automation Campaign ID is required.
FAILURE: A problem was encountered when attempting to create this List Definition.
 (Common for invalid formatting in Email style fields)

Arguments

The command supports the following arguments (See List Properties for more information about each field):

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=createlistdefinition
c=createlistdefinition

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 definition 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 definition.

description=[text]

Template

 

The default template associated with the list definition.  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]

Admin Email  

Email address to receive notifications when Campaigns have been sent or failed.  These notifications are in addition to the normal notifications sent to the User who deployed the Campaign.  

admin_email=[admin_email_address]

Account Profile    Identifier of the default Account Profile to use when deploying a campaign and filling the tags in content. Use Get Account Profile to find the ID.

acct_pro_id=[account_profile_id]

DEFAULT==Account Default Profile

Labels   

Comma separated list of identifiers of custom keywords to identify and report items that have a similar use or purpose.

labels=[label_id(s)]

Folder    Identifier of the Folder to associate the List for organization.  Default folder is 0, or Unfiled.

folder_id=[folder_id]

DEFAULT==0

Subscribe Confirmation Message   

To require Subscribers to confirm subscription requests, set the flag to '1'.  If the Flag is set, then the three additional fields are optional.
If no From Address is defined, it will use the List's From address.  
If no Template is defined, it will use a system default message.
If no Format is defined, the default is Plain Text.  Formats include:

  • 1= Plain Text
  • 2 = HTML

subscribe_confirmation_flag=[0,1]

DEFAULT==0

subscribe_confirmation_from_address=[email]
subscribe_confirmation_template_id=[template_id]
subscribe_confirmation_format=[1,2]

DEFAULT==1

Subscribe Courtesy Message   

To send a courtesy welcome message when Subscribers request subscription, set the flag to '1'.  If the Flag is set, then the three additional fields are optional.  

If no From Address is defined, it will use the List's From address.  
If no Template is defined, it will use a system default message.
If no Format is defined, the default is Plain Text.  Formats include:

  • 0 = Subscriber Selected Format
  • 1= Plain Text
  • 2 = HTML
  • 99 = Multipart MIME

subscribe_courtesy_flag=[0,1]

DEFAULT==0

subscribe_courtesy_from_address=[email]
subscribe_courtesy_template_id=[template_id]
subscribe_courtesy_format=
[0,1,2,99]

DEFAULT==1

Unsubscribe Courtesy Message  

To send a courtesy farewell message when Subscribers unsubscribe from a list, set the flag to '1'.  If the Flag is set, then the three additional fields are optional.  

If no From Address is defined, it will use the List's From address.  
If no Template is defined, it will use a system default message.
If no Format is defined, the default is Plain Text.  Formats include:

  • 0 = Subscriber Selected Format
  • 1= Plain Text
  • 2 = HTML
  • 99 = Multipart MIME

unsubscribe_courtesy_flag=[0,1]

DEFAULT==0

unsubscribe_courtesy_from_address=[email]
unsubscribe_courtesy_template_id=[template_id]
unsubscribe_courtesy_format=
[0,1,2,99]

DEFAULT==1

Default Automation Campaign   To deploy the selected Automation Campaign to each subscriber generated subscription request, set the flag to '1'.  If set, the ID is required. 

default_automation_flag=[0,1]
default_automation_campaign_id=[automation_id]

DEFAULT==0

Subscribe Landing Page

  Define a list specific Welcome landing page by entering a fully qualified URL.  The field accepts a URL up to 128 characters long. 

subscribe_landing_page_url=[URL]

Unsubscribe Landing Page

  Define a list specific Farewell landing page by entering a fully qualified URL.  The field accepts a URL up to 128 characters long. 

unsubscribe_landing_page_url=[URL]

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

Base URL

  Customize the tracking URL by defining a Base URL ID.

base_url_id=[base_url_id]

 VMTA   Customize the IP to use for publishing by defining a VMTA ID.

vmta=[vmta_id]

Forward to a Friend  

Define URLs to customize the form and landing pages for each list by entering the fully qualified URL to the content in the correct FTAF field. 

If the FTAF form will be used on a webpage instead of in an email, set the Allow Anon flag to '1'.

To use the List from address instead of sender's address, set From flag to '1'.

ftaf_custom_form_url=[URL]
ftaf_envelope_url=[URL]
ftaf_landing_page_url=[URL]
ftaf_error_landing_page_url=[URL]

ftaf_allow_anon_flag=[0,1]

DEFAULT==0

ftaf_user_list_from_flag=[0,1]

DEFAULT==0

Dedupe   To send only one message per email address when the resulting List is deployed, set the flag to '1'.  

dedupe_on_send_flag=[0,1]

DEFAULT==0

Sticky Campaign   To to aggregate all tracking from any Campaign sent over time via the resulting List into a single Campaign report, set the flag to '1'.

sticky_campaign_flag=[0,1]

DEFAULT==0

Set Data Macro  

Identifier of the macro to use to set the value of one to three custom fields for each subscriber when a campaign is deployed using the resulting List.

set_data_macro_id=[set_data_macro_id]

Workflow Approval   To require approval before deploying campaigns from the resulting list, set the flag to '1'.  If set, the email is required.  Email allows a comma separated list of one or more email addresses. 

workflow_flag=[0.1]
workflow_email_addresses=[email(s)]

DEFAULT==0

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

list_unsubscribe_flag=[0,1]

DEFAULT == 0

list_unsubscribe_email=mailto%3a[email]
list_unsubscribe_http=http%3a%2f%2f[url]

Event Macros   To use Event Macros when a campaign is sent from the resulting List, set the Sync flag to '1'.  If set, then define each optional Sync type by adding the Event Macro ID.

sync_flag=[0,1]

DEFAULT==0

sync_open=[event_macro_id]
sync_click=[event_macro_id]
sync_opt_in=[event_macro_id]
sync_opt_out=[event_macro_id]
sync_soft=[event_macro_id]
sync_hard=[event_macro_id]
sync_complaint=[event_macro_id]
sync_send=[event_macro_id]

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

Comments

Powered by Zendesk