Description
This method enables a 250OK Inbox Monitor report to be requested for a specified transactional template. To use this method, your account must have the 250OK Inbox Monitor feature enabled.
The best results for a transactional 250OK Inbox Monitor deliverability report are obtained when the template uses data representative of real recipients. Therefore, this API allows for sample .xml template data to be included with the API call via FTP or data URL.
Since send times for transactional messages can be unpredictable – triggered by a customer action – this method includes random schedule options when requesting an Inbox Monitor test. While best practices suggest testing transactional deliverability at least once a week, random options for this method allow for monthly or weekly settings. (Note: a week is Sunday to Saturday, so setting up a random option with multiple tests in the middle of a week will execute all of the first week's tests by Saturday.) The mandatory ok_im_schedule argument alternately allows for a single send at a fixed time specified by the marketer.
Arguments
| Field | Description | Field Type | Required | Example |
|---|---|---|---|---|
| template_id | The template identification number of the template to be tested. | number | Yes | 1234 |
| email_preference | A string consisting of one of three values: mime, html, and plain. This determines which version of the message the system will send the recipient. Defaults to 'mime'. |
string | No | mime |
| sample_data | Accepts either a <data_url> or FTP tags as child tags for <sample_data>. Any other child tag will be simply discarded and not treated as smarty content. | string | Yes | code, variable amounts |
| {$smarty} variables | Refer to the Smarty Templating guide here. | string | No | {order_id} |
| data_url | The URL of the data source located on the Internet. Allowable file extension is .xml only. | string | Conditional; required if not using FTP as the transfer protocol | https://www.mysite.com/data/content.xml |
| ftp_server | IP address or host name of your FTP server. | string | Conditional; required if file transfer is via FTP | ftp.mysite.com |
| ftp_user_name | FTP username | string | Conditional; required if file transfer is via FTP | ftp_user |
| ftp_user_pass | FTP password | string | Conditional; required if file transfer is via FTP | ftp_pass |
| filename | Name of data file on FTP server (may include file path). Allowable file extension is .xml | string | Conditional; required if file transfer is via FTP | datafile.xml or /path/to_file/datafile.xml |
| sftp | Indicator of whether connection is via the sFTP protocol where:
|
Boolean | No | 1 |
| ftp_ssl | Indicator of whether FTP with a valid SSL certificate should be applied where:
|
boolean | No | 1 |
| ok_im_schedule | Type of send for the 250OK Inbox Monitor request: random or scheduled time(s). Acceptable values are 'ok_random' or 'ok_scheduled' | conditional | Yes | ok_random |
| ok_occurence | If ok_random is specified, the ok_occurence tag is also required. Acceptable values are:
|
string | conditional | 2 times per week |
| ok_schedule_time | If ok_scheduled is specified, then ok_schedule_time tag is also required. The date must be submitted in YYYY-MM-DD:HH:II format | date | conditional | 2016-05-25:11:11 |
Response
| Field | Description | Example |
|---|---|---|
| template_id | The ID number of the template for which an Inbox Monitor report is requested. | 1055589 |
Response Codes
| responseCode | responseText | Description |
|---|---|---|
| 208 | Transactional 250OK Inbox Monitor test requested | Test transaction sent with 250OK Inbox Monitor test requested |
| 401 | Invalid File type provided. Only .xml file type is allowed. | Invalid File type provided. Only .xml file type is allowed. |
| 402 | Data source not specified | If a malformed URL is passed in data_url tag |
| 404 | URL for data file: is not found | The passed URL results in a "page not found" |
| 405 | Not all variables passed through | Missing any ftp tag or data file is not found on the FTP/SFTP site |
| 409 | Failed to download file from: | Unable to connect to FTP/SFTP site to retrieve data file |
| 429 | Invalid Template ID | The Template ID does not exist. |
| 437 | Invalid Template Data | The template data is not valid |
| 440 | Unable to Send, Inactive Template | The specified template is not active |
| 481 | No sample content available for the specified template | The template does not have stored/saved smarty replacement variable defaults defined |
| 482 | Unable to send, schedule parameters not included | Schedule not set or available (for scheduled send request) |
| 483 | Did not send, 250OK report event limit has been reached | Inbox Monitor event limit reached |
| 490 | 250OK account not provisioned | Did not send, 250OK account not provisioned for this account |
| 491 | 250OK report feature not enabled | Did not send, 250OK report feature not enabled for this account |
Example Post
<methodCall>
<methodName>transactional.sendokinboxmonitor</methodName>
<template_id>4669557</template_id>
<email_preference>html</email_preference>
<im_schedule>ok_random</ok_im_schedule>
<ok_occurrence>1 time per week</ok_occurrence>
<sample_data>
<ftp_server>ftp.example.com</ftp_server>
<ftp_user_name>xy_api</ftp_user_name>
<ftp_user_pass>pass111</ftp_user_pass>
<filename>example/golf_xmldata1-2016-02-25.xml</filename>
<ftp_ssl>0</ftp_ssl>
<sftp>0</sftp>
</sample_data>
</methodCall>
Example Response
<methodResponse>
<item>
<methodName>transactional.sendokinboxmonitor</methodName>
<responseText>Transactional 250OK Inbox Monitor test requested</Sent Transaction</responseText>
<responseCode>208</responseCode>
<responseData>
<template_id>4669557</template_id>
</responseData>
<responseNum>1</responseNum>
</item>
</methodResponse>