Schedule a mailing - ScheduleMailing

Use the ScheduleMailing API call to perform an immediate or scheduled send via the API. Do not provide an existing Mailing ID because it doesn't produce the desired result.

📘

Note

This API will not override the org email throttling setting. The API will honor all org level settings.

🚧

ScheduleMailing best practice

Implement a strict folder policy to better categorize and manage the sent mailings produced by this API. Acoustic Campaign recommends users adopt a Year/Month/Day or similar folder structure by including an appropriate value for the PARENT_FOLDER_PATH element and making use of the CREATE_PARENT_FOLDER element when applicable.

Elements (Required)

TEMPLATE_ID - The ID of template to base the mailing. You can get the Template ID from the Email campaigns view and hovering your mouse over the email name. The Template ID identifies which template is used to either schedule or immediately send and to provide a MailingID value upon its success.

LIST_ID - The ID of database, query, or contact list to send the template‐based mailing.

MAILING_NAME - The assigned name for the generated mailing.

VISIBILITY - Indicates where to save the sent mailing: 0 (Private Folder) or 1 (Shared Folder)

Elements (Optional)

SEND_HTML - If this element is present, value is true. Leave blank if you do not want to include the HTML body.

SEND_TEXT - If this element is present, value is true. Leave blank if you do not want to include the text body.

SUBJECT - If you do not include this element, Acoustic Campaign uses the subject saved with the template.

FROM_NAME - If you do not include this element, Acoustic Campaign uses the From name saved with the template.

FROM_ADDRESS - If you do not include this element, Acoustic Campaign uses the From address saved with the template.

REPLY_TO - If you do not include this element, Acoustic Campaign uses the Reply To address saved with the template.

CUSTOM_OPT_OUT - If you provide the element, it should contain a custom opt-out name that you added in the Org Admin Opt-Out settings. If the element is not provided, the standard opt-out should be applied. If the element is provided, but a custom opt-out link is not included in the template, the element will be ignored.

PARENT_FOLDER_PATH - The folder where you want to store your sent mailing.

CREATE_PARENT_FOLDER - Creates a folder if the path does not already exist.

SCHEDULED - Specifies the date and time when the mailing is scheduled to send. If this is not included, the mailing is sent immediately. The format must be: MM/DD/YYYY HH:MM:SS AMPM

PRE_PROCESSING_HOURS - Specifies if Acoustic Campaign should pre-process the contact source before send time. Must be an integer between 1 and 24. If this is not included, the contact source will be evaluated for eligible recipients at the mailing’s scheduled send time.

VMTA - Schedules the mailing using that VMTA (Virtual Mail Transport Agent), bypassing any defaults used by the mailing’s contact source. You must use the VMTA name and not the Friendly name when declaring this element.

SEND_TIME_OPTIMIZATION - Sends the mailing over a day or week. Valid values are:

• NONE – Does not use Send Time Optimization
• SEND_24HRS – Sends over a 24-hour period based on each recipient’s optimal send time
• SEND_WEEK– Sends over a 7-day period based on each recipient’s optimal send time

WA_MAILINGLEVEL_CODE - Specifies a mailing specific parameter to be passed via your links to your Site Analytics package. Must use with a Site Analytics Append String containing %%WA_MAILINGLEVEL_CODE%%. This element is equivalent to the Mailing Specific Parameter box on the Send Mailing screen in Acoustic Campaign when using Site Analytics.

SUPPRESSION_LISTS - XML node containing one or more SUPPRESSION_LIST_ID child elements.
SUPPRESSION_LIST_ID - If any suppression lists are specified, they are used as the suppression lists when the mailing is sent.

SUBSTITUTIONS - XML node containing child element SUBSTITUTION and its children.
SUBSTITUTION - Defines the substitution name and value to allow template‐level substitutions separate from the normal contact‐level substitutions performed by personalization. They are not contact specific. They are also not related to HTML_GENERAL_DISCLAIMER or the TEXT_GENERAL_DISCLAIMER.
NAME - Required for SUBSTITUTION The substitution tag used in the mailing template; it is case‐sensitive. For example, if you include %%Sub_Value_1%% in the mailing template, the value for this child element is SubValue_1.
VALUE - _Required for SUBSTITUTION The value to substitute into the mailing for the tag with the specified name.

EXT_SYSTEM_NAME - Use this attribute to specify the external system name for email events or to use your own naming convention.

EXT_SYSTEM_REFID - Use this attribute to specify the external system reference ID for email events.

<Envelope>
   <Body>
      <ScheduleMailing>
         <TEMPLATE_ID>1000</TEMPLATE_ID>
         <LIST_ID>100</LIST_ID>
         <MAILING_NAME>New Mailing Name</MAILING_NAME>
         <SEND_HTML />
         <SEND_TEXT />
         <SUBJECT>New subject</SUBJECT>
         <FROM_NAME>Senders Name</FROM_NAME>
         <FROM_ADDRESS>[email protected]</FROM_ADDRESS>
         <REPLY_TO>[email protected]</REPLY_TO>
         <VISIBILITY>0</VISIBILITY>
         <PARENT_FOLDER_PATH>Sent Folder Name</PARENT_FOLDER_PATH>
         <CREATE_PARENT_FOLDER />
         <SCHEDULED>10/13/2011 12:00:00 AM</SCHEDULED>
         <SUPPRESSION_LISTS>
            <SUPPRESSION_LIST_ID>37782</SUPPRESSION_LIST_ID>
            <SUPPRESSION_LIST_ID>37744</SUPPRESSION_LIST_ID>
         </SUPPRESSION_LISTS>
         <SUBSTITUTIONS>
            <SUBSTITUTION>
               <NAME>Sub_Value_1</NAME>
               <VALUE>The value to put in the mailing.</VALUE>
            </SUBSTITUTION>
            <SUBSTITUTION>
               <NAME>Sub_Value_2</NAME>
               <VALUE>Another value to add</VALUE>
            </SUBSTITUTION>
         </SUBSTITUTIONS>
        <EXT_SYSTEM_NAME>Campaign</EXT_SYSTEM_NAME>
        <EXT_SYSTEM_REFID>camp:1234,run:5678</EXT_SYSTEM_REFID>
      </ScheduleMailing>
   </Body>
</Envelope>

<Envelope>
   <Body>
      <RESULT>
         <SUCCESS>TRUE</SUCCESS>
         <MAILING_ID>9700</MAILING_ID>
      </RESULT>
   </Body>
</Envelope>

Elements (Results)

SUCCESS - True if successful; False if not.

MAILING_ID - The ID for the sent mailing. You can get the Mailing ID from the Email campaigns view by hovering over the email name.

Error codes