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

If the specified template has any unpublished changes, this API method will the publish the draft version of the template when making the Inbox Preview report request. If the specified template has no unpublished changes, then this API will use live version of the template for requesting the Inbox Preview report.

Best results for a transactional Inbox Preview rendering 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.


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


Field Description Example
template_id The ID number of the template for which an Inbox Preview report is requested. 1055589

Response Codes

responseCode responseText Description
207 Transactional Inbox Preview test requested Test transaction sent with Inbox Preview 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
428 Missing variables If any required tag is not provided in the API call
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
483 Did not send, Return Path report event limit has been reached Inbox Monitor event limit reached

Example Post









Example Response








<![CDATA[Template ID 1234567-test cache has been rebuilt.]]>



<![CDATA[Sent Transaction]]>



<![CDATA[Transactional Inbox Preview test requested]]>



















<![CDATA[Inbox Preview Report]]>











Back to API Reference Guide