This method enables an Inbox Monitor report to be requested for a specified transactional template. To use this method, your account must have the Return Path feature enabled.

Best results for a transactional 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 im_schedule argument alternately allows for a single send at a fixed time specified by the marketer.


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
ftp_server IP address or host name of your FTP server. string Conditional; required if file transfer is via FTP
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:
  • 0 – Do not connect via sFTP (default)
  • 1 – Connect via sFTP
Boolean No 1
ftp_ssl Indicator of whether FTP with a valid SSL certificate should be applied where:
  • 0 – Do not apply SSL certificate (default)
  • 1 – Apply SSL certificate
boolean No 1
im_schedule Type of send for the Inbox Monitor request: random or scheduled time(s). Acceptable values are 'random' or 'scheduled' conditional Yes random
occurence If random is specified, the occurence tag is also required. Acceptable values are:
  • 1 time per week
  • 2 times per week
  • 3 time per week
  • 4 times per week
  • 1 time per month
  • 2 times per month
  • 3 times per month
  • 4 times per month
string conditional 2 times per week
schedule_time If scheduled is specified, then 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


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
206 Transactional Inbox Monitor test requested Test transaction sent with 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
479 Return Path account not provisioned Did not send, Return Path account not provisioned for this account
480 Return Path report feature not enabled Did not send, Inbox Monitor feature not enabled for this account
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, Return Path report event limit has been reached Inbox Monitor event limit reached

Example Post






<occurrence>1 time per week</occurrence>










Example Response




<responseText>Transactional Inbox Monitor test requested</Sent Transaction</responseText>








Back to API Reference Guide