Friday, November 06, 2009

New API Method for Template-Driven Transactional Emails


Marketers can now create and edit Transactional Email Templates on the Send Email Page and without the help of their IT team.

To enable this, we launched a new API method: SendTransactionalEmailFromTemplate. Instead of passing the full details of the email message using the regular SendTransactionalEmail method, you can now simply pass the email Campaign ID and let your marketers use the JangoMail interface to dictate the email's creative content.

SendTransactionalEmailFromTemplate works like the SendTransactionalEmail method, but does not require you to enter FromEmail, FromName, Subject, MessagePlain, and MessageHTML. Instead you must enter CampaignID, PersonalizationValues, PersonalizationColDelimiter and PersonalizationFields.

Input Parameters

Your JangoMail account username

Your JangoMail account password

Marketers should create an Email Campaign as they normally would, starting on the Send Email Page (or just use the SendMassEmail API method). Once they create a campaign and send a test, you can find the Campaign ID in the Reporting and Analytics section of the JangoMail interface. Look in the ID column to find the Campaign ID.

The single email address to whom you want to send this email message.


JangoMail uses the following syntax for personalization and Marketers should continue to use this when creating transactional email templates. Mail-merge personalization tags can be used in the Subject, HTML Message, Plain Text Message, From Display Name, and From Email Address:

%%FieldName**Default Value%

The second version of the personalization syntax can be used in cases where the value of FieldName is blank, such that a default value is substituted instead of a blank. 


Specify a column delimiter as follows:
c for a comma
s for a space
n for a newline, or a hard break
t for a tab

A comma separated list of name/value pairs.  The names of the various options and their associated values are explained below.
You may specify:
TransactionalGroupID (a numeric ID of a previously created Transactional Group)
SkipUnsubCheck ("True" or "False")

You can also specify the following, but if not specified, values will pull from your original email campaign. User-specified values here will override values in your email campaign:

ReplyTo (any valid email address)
CC (any valid email address)
BCC (any valid email address)
CharacterSet (a character set like "ISO-8859-1" or "US-ASCII")
Encoding (either "7 bit" or "Quoted Printable" or "Base 64")
Priority (either "Low", "Medium", or "High") 
UseSystemMAILFROM ("True" or "False") 
Receipt ("True" or "False")
Wrapping (a numeric value from 0 to 100, with 0 meaning no wrapping takes place)
ClickTrack ("True" or "False") 
OpenTrack ("True" or "False")
NoClickTrackText ("True" or "False") 
Attachment1 (the name of a previously FTPd file, like "Invoice.pdf")
(the name of a previously FTPd file, like "Invoice.pdf")
Attachment3 (the name of a previously FTPd file, like "Invoice.pdf")
Attachment4 (the name of a previously FTPd file, like "Invoice.pdf")
Attachment5 (the name of a previously FTPd file, like "Invoice.pdf")


In the below example, the input parameters are:


This example assumes that the Subject and/or Body contains personalization placeholders for FirstName and OrderNumber.  In fact, for Campaign ID 265987456, the actual message is:

------BEGIN MESSAGE-------
Dear %%FirstName**Valued Customer%%,

Your order has shipped.  Your order number is %%OrderNumber%%.
------END MESSAGE-------

This transactional email will be open tracked.  To ensure that it will also be click tracked, we would add "ClickTrack=True" to the Options parameter.  If we wanted it to be a high priority message instead of the default medium priority, we could add "Priority=High", such that the full Options string would look like:,OpenTrack=True,ClickTrack=True,Priority=High

To test the operation using the HTTP POST protocol, visit the JangoMail API page on this method and click the Invoke button.

Frequently Asked Questions

Q. What's the difference between SendTransactionalEmailFromTemplate and SendTransactionalEmail?
A. When calling SendTransactionalEmail, you are passing in the full details of that email message, including the Subject, the HTML Message, the Plain Text Message, tracking options and much more.  However, if you've already created a template message in the Send Email section of the JangoMail web interface, you can call SendTransactionalEmailFromTemplate to send transactional emails and avoid having to pass in all the message details on every method call.  You simply reference the Campaign ID of the email message that you created in the Send Email section.

Q. I see there's a PersonalizationColDelimiter input paramter.  Where is the PersonalizationRowDelimiter input parameter?
A. Since this is a method to send a single transactional email, only one set of values can be provided for the single recipient of the email message.  There is no need for a row delimiter since the data should only be for one record.

Q. What is the TransactionalGroupID?
A. This is an optional setting that can be specified as part of the Options input parameter.  Transactional Groups are a way to categorize different types of transactional emails, like Order Confirmations, Shipping Notifications, and Thank You messages.  You can create different Transactional Groups using the web interface or by calling AddTransactionalGroup.  Every Group has a numeric ID assigned to it, and so to assign a particular transactional email to a Group, you can set the TransactionalGroupID.

Q. How do I send attachments with my transactional email?
A. You can specify the names of attachments in the Options input parameter.  However, the file names you specify must already be present in your account.  You should FTP your files to prior to calling this method with attachments.