API: HTTP Launch Campaign

The Launch command allows you to deploy a campaign to a List of contacts or a Segment of a List. It requires the following arguments: Command, Realm, Password, List and Format.

api_web?r=myrealm&p=mypass&c=launch&list_id=5&format=2

The command is ‘launch’, the realm is ‘myrealm’ and the password is ‘mypass’. The list properties are defined in list with ID ‘5’, the template content to send is defined in the list properties, and all contacts in the list will receive the HTML content format.

Before deploying a campaign, every email address to receive the message must be subscribed to the list. If a contact does not exist or is not subscribed to the list, no message will be sent to that contact. In order to send a message to a non-contact (such as an order confirmation), please use the send command.

When you call the Launch command, a campaign is created and all data collects as part of this campaign. However, the Launch command does not check to ensure contacts exist in the list or list segment. If there are 0 contacts, the command will return SUCCESS, but no campaign will deploy.

Return Count

The Launch command can also return the contact count for the campaign by using the command 'launchwithcount'. It works the same as the basic 'launch' but also returns the number of pieces sent.

Super List

Prior to v12.06.0, Launch deploys campaigns of type Normal only and does not deploy a Super List. Super Lists can only be deployed through the user interface or in versions before v12.06.0.

Customized Content

Templates support the option of sending customized information. While you can pass in custom data with the Send command, the Launch command can only use the data associated to each contact for each message.

However, you can customize the List From and Reply To address using custom contact data fields. This can be accomplished by setting the custom data in the List properties (From = "%%$myfrom%%" %%$myemail%%>).

When the message is sent, the publisher will grab the data stored in the Contact's custom data field to fill in the address settings:

From: "My Custom From Address" <mycustomemail@domain.com>

Example

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

api_web?c=launch&r=myrealm&p=mypass&list_id=5&template_id=42&seed_list_id=6&subject=New%20Subject&format=99&vmta=myvmta&segmentation_id=9&campaign_alias=Test&email_phase=convert&email_type=service&email_category=reengagement&notify_email=notify@domain.com&delivery=0

A message from List ‘5’ with MIME merged content from Template ‘42’ will be sent to all contacts that match the rules defined in segmentation rule ‘9’. The default Template Subject will be replaced in the resulting message. The message will be sent through the 'myvmta' IP. Successful results return:

SUCCESS:

Alternately, to send an A/B Test, use the command in the following format:

api_web?c=launch&r=myrealm&p=mypass&ab_definition_id=132&deployed_by_email=myemail@mydomain.com

Results

The Launch command outputs either a SUCCESS or FAILURE message.

SUCCESS

The basic Launch command success message is the simple word 'SUCCESS'. The result format is:

SUCCESS:

The Launch command with the additional 'withcount' returns the number of contacts currently matching the List Count minus any Segment or Suppression rules. The result format is:

SUCCESS: [number_pieces_sent]

The Launch command with the additional 'return_task_id' returns the identification number of the list and the task created for the campaign to launch. The result format is:

SUCCESS: list_id [list_id] launched. Task ID: [task_id]

FAILURE

A Launch command will fail for several reasons, such as if the list does not exist or the From Address is missing. The result format is:

FAILURE: [Reason]

Arguments

The Launch commands support the following arguments:

Name	Req?	Description	Argument
Command	Yes	Defines the command to use.	cmd= [launch, launchwithcount] c=[launch, launchwithcount] *listrun and listrunwithcount prior to v10 also acceptable
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 ID	Yes	Identifier of the list properties to use.	list_id=[list_id]
Template ID		Identifier of the template content to send. If no template id defined in the call, the default template defined in the List properties will be used. If no template is defined there, the call will fail. In the template, both formats must be defined in order to send MIME.	template_id=[template_id]
Subject		Subject line of the message to send. This overrides the default Subject defined in the Template. Character limit is 48.	subject=[text]
Seed List		To seed a campaign with test addresses from a Seed List, set the seed_list id.	seed_list_id=[seed_list_id]
Suppression List		To suppress contacts in the list from receiving the message, use the Suppression List by defining the Name of the Suppression List. *Added in v16.18	suppression_list=[suppression list name]
Segmentation Rule		Identifier of the segmentation rule to use to limit the contacts. If no segmentation rule is specified, the campaign will deploy to every contact in the List.	segmentation_id=[segmentation_rule_id]
Format	Yes	To specify the format of the email messages, set Format to the corresponding value: 1= send Plain Text only 2 = send HTML only 99 = send Multipart MIME	format=[1,2,99]
Campaign Alias		An optional text string to help you distinguish the campaign from others deployed from the same list.	campaign_alias=[text]
Virtual MTA		Name of the Virtual MTA IP address through which to deploy the messages. If not defined, the VTMA set in the List properties will be used.	vmta=[vmta_name]
A/B Definition		Identifier of the A/B Test Definition to deploy to contacts. List, Template, and Segment are not required or used when A/B Definition is used because the List, Template, and Segment are defined in the A/B Definition.	ab_definition_id=[ab_definition_id]
A/B Deployed By Email		Email address of the realm User deploying the A/B test. if the email address does not match a User in the realm, then the command will fail. Required when sending A/B Test.	deployed_by_email=[email address]
Return Task ID		On a successful launch, return the identifier for the created task if set to 1.	return_task_id=[0,1] DEFAULT==0
Seed Delivery		To seed a campaign with email addresses associated with monitored mailboxes, set delivery to 1 and include the notify_email. This feature is limited in its availability and must be enabled in your Realm settings. When the campaign is complete, the results of the Deliverability Report are available in the Campaign Details in the UI. If no deliverability reports are available, the launch will succeed but with an error. The campaign will deploy, but the inbox seed will not occur and no delivery report will appear in the campaign details. SUCCESS: list_id 5 launched: Launch success, delivery report failed with no available reports	delivery=[0,1]&notify_email=[email address] DEFAULT==0 Released in v10.8.0
Send Notification		After the campaign has completed, a notification email will be sent to the specified email address.	notify_email=[email address]
Email Campaign Labels		Define labels to associate the campaign for later reporting, including Email Phase, Type, and Category. Labels are optional. The label name must match a valid label of the specified type already defined in your Realm. Use Get Email Labels to get a list of defined Campaign Labels. Email Campaign Label support added in v12.06.0. Email Campaign Label support is deprecated in v15.14.0 in preference to new Label support.	email_phase=[phase_name] email_type=[type_name] email_category=[category_name]
Account Profile		To use an Account Profile other than that assigned to the list, define the Account Profile ID. Account Profile support added in v12.03.0.	acct_pro_id=[account_profile_id]
Email Snapshot		Email Snapshot will create and store the HTML and image screenshot of each message sent, including contact-specific personalization. If your Realm is enabled for Email Snapshot, to store a copy of each message, set the 'snapshot' argument to 1. Email Snapshot support added in v15.00.00.	snapshot=[0,1]
Labels		Comma separated list of up to 10 labels, identifiers of custom keywords to group and report items that have a similar use or purpose. The label(s) must be defined for the Realm in order to save. Use Get Labels to see a list of valid labels. Label support added in v15.14.00 to replace deprecated Email Campaign Labels.	label=[label_name(s)]
Google Analytics		To include Analytics tags in your tracking URLs, the 'ga' argument must be set to 1. If no UTM arguments are included in the command, then the default UTM settings from the Account will be used. To customize the UTM setting for the specific command, add the &utm_ tag followed by a string value. To ignore the default value from the Account, use the &utm Remove argument set to 1. For example, to use the default source, medium and campaign, but use a custom content, and blank term, use the following set of arguments: &campaign_name=GoogleEnabled&ga=1&utm_content=Custom%20Content &utm_term_remove=1 Google Analytics support added in v12.13.0.	&ga=[0,1] &utm_source=[string] &utm_medium=[string] &utm_campaign=[string] &utm_content=[string] &utm_term=[string] &utm_source_remove=[0,1] &utm_medium_remove=[0,1] &utm_campaign_remove=[0,1] &utm_content_remove=[0,1] &utm_term_remove=[0,1]