legacy.send_campaign

‹ BACK TO API PAGE


Description

WARNING: This method cannot be combined with any other method call within the same POST command.

This method lets you integrate your database marketing system and content management system with the eMS Enterprise platform for sending the email to a specified segment of recipients. Key features include the ability to upload both HTML and plain text content for your email, to send the message immediately or to schedule a message to be sent at a future date and time, and to identify a segment from your email marketing database who should be excluded from receiving the email.

The default behavior of this method is to create a Draft message that may be deployed by using Step 2 of this method or by logging into eMS Enterprise and clicking the [Send Message] button. You can, however, use this method to tell eMS Enterprise to send the message directly without any manual intervention. This direct send capability is a two-step process in which you first create the Draft message that is ready to be sent; then you POST a second message instructing eMS Enterprise to send the message.

Step 1:
POST the XML message using the arguments specified below. The POST response message will include a <message_id> element and a <message_key> element.

Step 2:
POST a subsequent message containing just the <message_key> element whose value is set to what was returned in the first POST response. The POST response message will include the results of the message send.

Arguments

Use the following parameters to create a Draft message

Field Description Field Type Required Example
grp A comma delimited list of the ID numbers of the static segments that are to receive this message. To view a list of static segments and their corresponding ID numbers, log in to eMS Enterprise and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID. string Conditional; required if <sm> element is not used 123123,112312
sm A comma delimited list of the ID numbers of the dynamic segments that are to receive this message. To view a list of dynamic segments and their corresponding ID numbers, log in to eMS Enterprise and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Segments section to find the dynamic segment name and its corresponding segment ID. string Conditional; required if <grp> element is not used 93429,29842
sm_exclude A comma delimited list of the ID numbers of the dynamic segments that are to be excluded from this message. To view a list of dynamic segments and their corresponding ID numbers, log in to eMS Enterprise and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Segments section to find the dynamic segment name and its corresponding segment ID. string No 93429,29842
rich_mbody The HTML content for the message string Yes see examples
text_mbody The plain text content for the message string Yes see examples
send Set to 'Y' to restrict sending of the message only via this API method string No Y
reply_email The email address where replies should be sent string Yes service@example.com
from_email The email address where the email should appear to come string Yes promotions@example.com
fromdesc The "friendly from name" visible to the subscriber string Yes Your Favorite E-Tailer
msubject The subject of the email string Yes Spring Offer 25% Off!
timed_release Set this element to 'Y' if you want to schedule the message to be sent at a later date and time. Otherwise, the message will be sent immediately. string No Y
date The date when the message is to be sent in YYYY-MM-DD format string Conditional; required if <timed_release> element is set to 'Y' 2005-12-15
hour The hour of the day in which to send the message (24 hour clock as an integer). All send times are in US Pacific Time Zone integer Conditional; required if <timed_release> element is set to 'Y' 13 (e.g. 1:00PM US Pacific Time Zone)
substitute_name A name that will be used when first name and last name personalization is used and a first name or last name does not exist for a given individual string No Subscriber
bill_codes A text field for customer's internal billing information string No Accounting code: 4398394
message_notes A text field for notes regarding the message up to a maximum of 128 characters. string No This message will be paid for by advertisers
campaign_id A campaign ID internal to the system to make this message part of a larger campaign number No
track_links Set this element to '1' if you want the system to track all links within the message number No 1
grp_exclude A comma-delimited list of static segment IDs that indicate static segments you wish to explicitly exclude from the mailing. To view a list of static segments and their corresponding ID numbers, log in to the application and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID. string No 49823,98432,138542
use_default_footer Set this element to '1' if you want the message to use the default footer associated with the primary user account. The default footer can be set in the UI under the Message Footers section by selecting 'Set as Default'. string No 1
binding This parameter is used to specify a specific IP address binding to be used for a message. Contact your Account Manager to find out which bindings are available for you to use. string No echo
throttle_rate Allows specification of the message send rate, using the same send values available in EMS. (Requires throttle rate feature enabled for EMS account.) number No 250,000
message_name Allows specification of a Message Name string No Fall Campaign
footer_id This parameter can be used to specify available account footers by footer ID for inclusion in the message. (Not applied if use_default_footer is called). number No 22263
inbox_monitor Requests an Inbox Monitor report. Set this element to '1' to request Inbox Monitor report for the specified campaign send. boolean No 1

 

After creating the Draft through this method, POST a follow up message to send it using the following parameter:

Field Description Field Type Required Example
message_key The unique identifier of the message draft created in the initial POST message string Yes 8ff953dd97c4405234a04291dee39e

Response

The response message from the first POST includes the following elements:

reasonThis element will only be included in the response message when the POST fails. This field will include the human-readable reason for the failure.timed-release day/time is in past.

Field Description Example
message A code indicating either a success ('1') or a failure ('2') to create the Draft message. 1
message_id The system-assigned message ID that can be referenced in other API method calls. This element will only be included in the response message when the POST is successful. 1029304
message_key The system-generated unique identifier that must be included in the POST message that instructs eMS Enterprise to send the newly created message Draft. This element will only be included in the response message when the POST is successful. 8ff953dd97c4405234a04291dee39e

 

The response message from the second POST includes the following elements:

Field Description Example
message A code indicating either a success ('1') or a failure ('2') to send the message. 1
sent This element will only be included in the response message when the POST is successful. The value is set to '1'. 1
reason This element will only be included in the response message when the POST fails. This field will include the human-readable reason for the failure. timed-release day/time is in past.

Response Codes

Response Code Response Text Description
201 sent The DRAFT message was successfully sent
202 draft key The new message was successfully created as a DRAFT
401 there was an error processing the message for delivery There was a system-level error encountered that prevented the message from being delivered.
402 the message could not be found The value of the <message_key> element did not correspond to a DRAFT message in your account.
403 timed release data not valid The values for the <date> and/or <hour> elements were not properly formatted
404 timed release day-time is in past The values for the <date> and/or <hour> elements were for a date and/or time that has since passed from the current system date/time.
405 no valid groups or smart lists selected for sending The values provided in the <grp> and/or the <sm> elements did not correspond to any static segments (a.k.a. groups) or dynamic segments (a.k.a. smart lists) in your account.
406 message_notes element exceeds maximum allowable characters The value provided in the <message_notes> element exceeds the 128-character limit.
407 the message was already processed for sending The value provided in the <message_key> element corresponds to a DRAFT that has already been scheduled for delivery.
430 Invalid binding value Binding is not assigned to the client
475 Action not taken, throttle_rate is greater than the maximum Throttle rate cannot be set to a value greater than the system maximum.
476 Action not taken, throttle_rate is not a recognized value The throttle rate must be set to one of the same values available from the EMS user interface.
477 Action not taken, message throttling not enabled for this account Message throttle can only be applied if the feature is enabled for the sending account.
478 Throttle_rate is not a valid argument in the 2nd POST for this method Throttle rate can only be applied for the 1st POST of this method.
480 Action not taken, submitted message_name already exists Message names must be unique.
482 Action not taken, footer_id is not a recognized value Specified footer must use one of the existing footer_id values. See Edit Message Footers for available values.
484 No Return Path account provisioned If inbox_monitor is invoked, but Return Path account is not set up for the eMS account.
485 Inbox Monitor feature is not enabled for this account If inbox_monitor is invoked, but the Inbox Monitor feature is not enabled for the eMS account.
486 Invalid value submitted for Inbox Monitor If inbox_monitor is invoked with a value other than the two valid flags (0 or 1).

Example Post

This is an example of the POSTed message used to create a Draft that should be flagged for sending:

<methodCall>

<methodName>legacy.send_campaign</methodName>

<grp>10</grp>

<rich_mbody>

<![CDATA[ ... HTML content goes here ...]]>

</rich_mbody>

<text_mbody>

<![CDATA[ ... Plain Text content goes here... ]]>

</text_mbody>

<reply_email>service@example.com</reply_email>

<from_email>promotions@example.com</from_email>

<fromdesc>Your Favorite E-Tailer</fromdesc>

<msubject>Spring Offer 25% Off!</msubject>

<track_links>1</track_links>

</methodCall>

This is an example of the POSTed message used to trigger the actual send of the newly created Draft message:

<methodCall>

<methodName>legacy.send_campaign</methodName>

<message_key>8ff953dd97c4405234a04291dee39e</message_key>

</methodCall>

Example Response

This is an example of the message sent in response to a successful POST in which the message should be automatically sent:

<methodResponse>

<item>

<message>1</message>

<message_id>1029304</message_id>

<message_key>8ff953dd97c4405234a04291dee39e</message_key>

</item>

</methodResponse>

This is an example of the message sent in response to a successful send:

<methodResponse>

<item>

<methodName>legacy.send_campaign</methodName>

<responseData>

<message>1</message>

<sent>1</sent>

</responseData>

<responseNum>1</responseNum>

</item>

</methodResponse>

Example Error

<methodResponse>

<item>

<methodName>legacy.send_campaign</methodName>

<responseData>

<message>2</message>

<reason>timed-release day/time is in the past</reason>

</responseData>

<responseNum>1</responseNum>

</item>

</methodResponse>


Back to API Reference Guide