transactional.sendTransaction

‹ BACK TO API PAGE


Description

Messages sent via this method are genuine transactional messages and are tracked as such. Sending through this method sends the live version of the template. The system tracks several statistics on all messages send via this method, including number sent, bounced, and opened. If the settings for the template are set to track links and ROI info, clicks will also track. The marketer can access template statistics within the application. Navigate to "Statistics -> Sent Messages -> Transactional" to access lifetime statistics for all transactional templates in the system.

Transactional messages created within the application can also be sent using this method.

NOTE: Recipients of the transactional message are NOT considered recipients of your promotional emails.  Only those individuals who have explicitly opted in to receive your promotional emails will receive these types of messages.  However, if during the course of a product/service purchase, a person has elected to receive marketing and product updates from your brand, then you can use this method to subscribe them to your email marketing database by including the <contact_add> element in the POSTed XML message that your system sends to eMS Enterprise.

Because recipients of transactional message are not necessarily opted in to receive promotional messages, you are responsible to honor any requests from your message recipients if they have elected to not receive any receipts or other types of confirmational messages.

BlueHornet will, however, not send a transactional message if an email record has been marked permanently invalid as a result of a hard bounce or three consecutive soft bounces.

Arguments

Field Description Field Type Required Example
email The email address you wish to send the transactional message to. string Yes jsmith@example.com
external_id A subscriber's identifier defined within an external system. This ID must be unique across all subscribers. string
64 characters max.
No ABC123DEF456
template_id The Template ID number of the template you wish to send. 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
name A string value that populates the "To:" value in the message header
with the email address.
string No James Smith
subject A string value containing the subject line of the message when sent to the transactional recipient.
Will override the default template value.
string No Your BB Order Confirmation
from_description A string value that populates the "From:" value in the message
header, along with the from email address. Email clients commonly
display this value in the users' inbox.
Will override the default template value.
string No Buffalo Barn
from_email A string value that populates the "From:" value in the message
header, along with the From Description.
Will override the default template value.
string No orders@buffalobarn.com
reply_email A string that populates the "Reply-To:" value in the message header.
Will override the default template value.
string No orders@buffalobarn.com
contact_add A Boolean value that will add the recipient to the marketing system
when this parameter is set to 1. The default value is 0.NOTE: Only use this element if a person has, during the product/service purchase process, explicitly opted in to receive product and marketing updates from your brand.
boolean No 1
check_optout A Boolean value that when set to 1 will check the email address against the system optout database and will not send if the contact has previously opted out. The default value is 0. boolean No 1
check_antispam_fields Set this element to '1' if anti-spam compliance custom fields should be checked for status and date boolean No 1
{$smarty} variables Refer to The Smarty Framework for Personalized Transactional Messaging. string No see examples below using {order_id}
do_not_log A Boolean value to indicate whether or not to store this specific method call in the API Request Log and the Historical Sent Log. This ensures a degree of security from anyone accessing the Logs and viewing any elements that have highly sensitive values.
  1. "0" = False
  2. "1" = True
boolean No 1
binding This parameter is used to specify a specific IP address binding to be used for a transactional message template. Contact your Account Manager to find out which bindings are available for you to use. string No echo
use_standard_footer A Boolean value that when set to 1 will include the standard footer in the message. Otherwise no footer is used. boolean No 1

Response

Field Description Example
email email address of the message recipient; it will be the same as the one passed in from the POST jsmith@example.com
contact_id (optional) This field will be returned if the value of <contact_add> was set to 1 in the POST 88615149

Response Codes

Response Code Response Text Description
201 Sent transaction The transactional message was successfully sent.
424 Invalid External ID The message recipient was identified via his External ID field value rather than his email address, and the ID was either not found or otherwise invalid.
428 Missing variables Required data was missing from the POSTed XML. The <responseData> element will include the name of the missing required element.
429 Invalid Template ID The Template ID does not exist.
430 Did not Send: Subscriber has Optout record <check_optout>1</check_optout> was included in the POSTed XML and the contact record was found to be already unsubscribed.
436 Invalid email address The email address is not valid
437 Invalid Template Data The template data is not valid
438 The external_id field must be less than 64 characters The value for external_id exceeds the maximum allowable number of characters
439 The external ID should contain alphabetic or numeric characters or both The external ID contains characters that are not allowed
440 Unable to Send, Inactive Template The specified template is not active
441 Did Not Send: Error Saving Message There was a problem with creating the message from the data provided
442 Did Not Send: Contact is Invalid The contact record is no longer valid
444 Invalid binding value The IP binding specified in the input parameters is not assign to this account
446 No XML data passed XML elements were not included in the API method call
448 Invalid or Inactive Template ID The Template ID provided in the input parameter is either invalid or inactive
465 Did Not Send: One or both compliance fields do not exist Message not sent, one or both compliance fields do not exist
466 Did Not Send: Compliance status is not a valid value Message not sent, compliance status field contains an unrecognized value
467 Did Not Send: Compliance date is past expiration or has a null value Message not sent, compliance not passed: implied status with date (compliance or date added) is two years or more, or has a null value (after grace period).

Example Post

<methodCall>

<methodName>transactional.sendtransaction</methodName>

<email>jsmith@example.com</email>

<template_id>1055589</template_id>

<email_preference>mime</email_preference>

<contact_add>1</contact_add>

<name>John Smith</name>

<order_id>1234</order_id>

</methodCall>

Example Response

<methodResponse>

<item>

<methodName>transactional.sendtransaction</methodName>

<responseText>Sent Transaction</responseText>

<responseData>

<email>jsmith@example.com</email>

<contact_id>88615149</contact_id>

</responseData>

</item>

</methodResponse>


Back to API Reference Guide