API: HTTP Schedule Campaign
The Schedule Campaign command allows you to set a campaign to deploy at a specific date and time on a one time or recurring basis.
The Schedule Campaign command requires the following arguments: Command, Realm, Password, List, Format, Start Date and Time.
api_web?r=myrealm&p=mypass&c=schedule_deployment&list_id=5&format=1&start_month=09&start_day=20&start_year=2012&hour=11&minute=30
The command is ‘schedule_deployment’, 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 be sent the Plain Text format at 11:30 am on September 20, 2012.
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.
The Schedule Campaign command does not check to ensure contacts exist in the list or list segment. If there are 0 contacts, the command will return SUCCESS and be scheduled. If there are no contacts at run time, no campaign will deploy and a failure message will be sent to the Notification email address.
Return Count
The Schedule Campaign command can also return the contact count for the campaign by using the command 'scheduledeploymentreturncount'. It works the same as the basic 'schedule_deployment' but also returns the number of pieces that would send if the campaign were to launch immediately. **
Super List
Prior to v12.05.0, Schedule Campaign deploys campaigns of type Normal only and does not deploy a Super List. Super List deployment can only be scheduled through the user interface or in versions before v12.05.0.
Time Zone
Schedule Campaign Start and End times are based on the system time zone, and ignore the timezone set for the Account. For example, if the database timezone is set to PST, but the Account uses EST when displaying the time in the user interface, the API will always schedule based on the PST time. Your campaign scheduled to run at 12:30 PM will deploy at 12:30 PM PST / 3:30 PM EST.
As of 12.06.0, you may select to use the Account's timezone instead with the use_timezone attribute. If use_timezone = 1, then your campaign scheduled to run at 12:30 PM will deploy at 12:30 PM EST.
Customized Content
Templates support the option of sending customized information. While you can pass in custom data with the Send command, the Schedule Campaign command will 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 most commands and arguments (please note the command is wrapped for display purposes only):
api_web?c=schedule_deployment&r=myrealm&p=mypass&list_id=5&seed_list_id=6&template_id=42&format=99&segmentation_id=9&suppression_list=suppress.txt&set_data_macro_id=40&start_month=09&start_day=26&start_year=2012&hour=09&minute=30&no_end_date=1&repeat_frequency=3&monday=1&wednesday=1¬ify_email=notify@domain.com&campaign_alias=Test&email_phase=convert&email_type=service&email_category=reengagement&delivery=0&use_timezone=1&verbose=1
A message from List ‘5’ with MIME content from Template ‘42’ will be sent to all contacts that match the rules defined in segmentation rule ‘9’ and are not in the suppression list 'suppress.txt'. The message will repeat weekly on Monday and Wednesday at 9:30 am starting on September 26, 2012. Successful results return:
SUCCESS
Results
The Schedule Campaign command outputs either a SUCCESS or FAILURE message.
SUCCESS
The Schedule Campaign command success message is the simple word 'SUCCESS'. The result format is:
SUCCESS
The Schedule Campaign command with the additional 'returncount' returns the number of contacts currently matching the List Count minus any Segment or Suppression rules.** The result format is:
SUCCESS: [count]
FAILURE
A Schedule Campaign command will fail for several reasons, such as if the List or Template does not exist, or the List is missing a From address. The result format is:
FAILURE: [Reason]
Arguments
The command support the following arguments:
Name | Req? | Description | Argument |
Command | Yes | Defines the command to use. | cmd=[schedule_deployment, scheduledeploymentreturncount] c=[schedule_deployment, |
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 | Yes | 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] |
Format | Yes | To specify the format of the email messages, set Format to the corresponding value: 0 = send Contact Selected Format | format=[0,1,2,99] |
Segmentation Rule |
| Identifier of the segmentation rule to use to limit the contacts. If no segmentation rule is specified or is set to 0, the campaign will deploy to every contact in the List. | segmentation_id=[segmentation_rule_id] |
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 recieving the message, use the Suppression List by defining the Name of the Suppression LIst. | suppression_list=[suppression list name] |
Set Data Macro |
| To set contact data when a campaign is deployed, define the Set Data Macro ID. | set_data_macro_id=[set_data_macro_id] |
Campaign Alias |
| An optional text string to help you distinguish the campaign from others deployed from the same list. | campaign_alias=[text] |
Limit* |
| To send to only a specific number of contacts, define a limit. This is useful for testing message content to a group of test contacts. Limit is not supported when sending an AB Definition. | limit=[integer] |
Fillin Fields* |
| If the List and Template contain fillin fields, set the values by defining the fillin_name and fillin_values, where N is a number starting with 0 up to 9 (limited to 10 fillin fields at this time). For example: &fillin_name0=Subject &fillin_value0=Welcome &fillin_name1=City &fillin_value1=Seattle **NOTE: If a fillin field has been defined as Required in a List, Template, or Article, then it must be defined in the Schedule Campaign command, otherwise the command will fail with the following error: FAILURE: missing value for required fillin field [fillin field name] | &fillin_nameN=[fillin_field_name] &fillin_valueN=[fillin_field_value] |
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 schedule will succeed but with an error. The campaign will deploy at the scheduled time, but the inbox seed will not occur and no delivery report will appear in the campaign details.
| delivery=[0,1]¬ify_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] |
Start Date | Yes | The date to start sending the campaign. If it is not defined, the campagain will be immediately deployed. mm = two digit number for the month, 01 to 12 | start_month=[mm] start_day=[dd] start_year=[yyyy] |
Start Time | Yes | The time to run the campaign. If it is not defined, the campagain will be immediately deployed. hh = two digit number for the hour in twenty four hour notation, 00 to 23 | hour=[hh] minute=[mm] |
End Date |
| The date to stop sending the campaign. If it is not defined, the campagain will be immediately deployed. mm = two digit number for the month, 01 to 12 | end_month=[mm] end_day=[dd] end_year=[yyyy] |
No End Date |
| To schedule a repeating campaign that never ends, set to 1 and do not define the End Date. If set to 1, any defined End Date will be ignored. | no_end_date=[0,1] DEFAULT==0 |
Workflow Send Time |
| Specify the number of hours prior to the scheduled time to send the Workflow message. This is only valid if Workflow is enabled for the list. hh = one or two digit number to indicate the hour from 0 to 72 | workflow_send_time=[hh] DEFAULT==0 |
Repeat Frequency |
| To schedule a repeating campaign, set the frequency. If set to weekly, you must also set the week day to 1 for each day to send. 0 = one time, do not repeat | repeat_frequency=[frequency] DEFAULT==0 sunday=[0,1] |
Use Time Zone |
| If your Account is set to use a timezone other than the default server timezone (usually PST), the campaign is scheduled using the default servers timezone To use the Account specific timezone instead, set to 1. *Time Zone option added in v12.06.0 | use_timezone=[0,1] DEFAULT == 0 |
Verbose |
| Set verbose to true to output XML formatted settings for the scheduled campaign. By default, this flag is set to false. | verbose=[0,1] |
Email Campaign Labels |
| Define labels to associate the campaign for later reporting. 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_label=[label_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 Google Analytics support added in v12.13.0. | &ga=[0,1] |
** Time Zone support, Email Campaign Label support, and Schedule Campaign with Count added in v12.06.0