Contents x
      transactional.sendTransaction
      • 4 Minutes to read
      • Print
      • Dark
        Light
      Contents

      transactional.sendTransaction

      • 4 Minutes to read
      • Print
      • Dark
        Light
      Article summary

      General Information

      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 sent via this method, including the 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 Empower Enterprise.

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

      Mapp 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.

      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 opt-out 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

      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 assigned 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>

      Was this article helpful?
      What's Next