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 Empower 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 Empower Enterprise and clicking the [Send Message] button. You can, however, use this method to tell Empower 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 Empower 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 Empower 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 Empower 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 Empower 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) |
| minute | The minute of the hour in which to send the message, used in conjunction with the <hour> parameter. All send times are in US Pacific Time Zone | integer | N. Will default to 0 if not included. | 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 Empower. (Requires throttle rate feature enabled for Empower 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 |
| range_total | This parameter is used to restrict the number of subscribers a message is sent to, regardless of the size of the selected segment(s). | number | No | 10000 |
| range_subtract | This parameter is used to exclude the first few rows of a selected segment | number | No | 5 |
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 Empower 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. |
| 408 | Custom message | This will be a customized message from the SmartyParser that details the error found. This will mimic the output that you would get from the UI editor. |
| 409 | The HTML markup for this message contains a dynamic content tag as well as template system notation. These 2 features are NOT compatible. You must revise this message to utilize only one of these features. | DC tags and Smarty tags are not compatible and cannot be used in the same message. |
| 410 | Template Error: An unknown error occurred, check your template variables and logic. | An error was found by the SmartyParser but could not be specified |
| 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 Empower 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 Empower 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 Empower 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>