TransactionalJobSubmit is used to send a single email to a single email address. This is the easiest way to send transactional email as it does not require the creation of a separate recipient file accessible to the MessageGears system. All data needed to fulfill the request is supplied in the API call.
Deprecated Versions
v3.0 (November 2010)
Required Parameters
| Parameter | Personalizable | Description |
| Action | TransactionalJobSubmit | |
| AccountId | The MessageGears account id to which this item belongs. | |
| ApiKey | A secret key only known by you. Keep this key confidential. | |
| FromAddress | Yes | The "from email address" value. This field can be personalized using one of the supported template languages. |
| SubjectLine | Yes | The value used as the subject line. You can personalize this field using one of the supported template languages. |
| RecipientXml | The XML for a single recipient supplied in the prescribed format. |
|
| HtmlTemplate | Yes | The HTML template used for the HTML part of the email messages. At least one template must be provided (Text or HTML). If both are provided then a “multipart” message is sent and each email recipient’s email reader determines which content type to display. |
| TextTemplate | Yes | The text template used for the text part of the email message. |
Optional Parameters
| Parameter | Personalizable | Description |
| FromName | Yes | The "from name" value. This header is supported by most email clients and displays in place of (or sometime along with) the “from email address” in the recipients email reader. |
| OnBehalfOfName | Yes | Sets the "On Behalf Of" name part of the "Sender" header. |
| OnBehalfOfAddress | Yes | Sets the "On Behalf Of" email address part of the "Sender" header. |
| ReplyToAddress | Yes | This email address is used when the client selects "reply to" in their email reader. If not specified, the from address is used. |
| TemplateLanguage | Valid values are: FREEMARKER or VELOCITY. If no value is specified, FREEMARKER is used by default. | |
| NotificationEmailAddress | If this value is specified, any errors that are encountered in processing the job are emailed to this address. This can be very helpful for initial development and testing. | |
| AttachmentUrl.n | The URL where the attachment file is located. As many as 5 attachments can be supplied. Each attachment must have the appropriate suffix (i.e. .1, .2, .3, .4, .5). |
|
| AttachmentContent.n | The base64 encoded string containing the attachment content. As many as 5 attachments can be supplied. Each attachment must have the appropriate suffix (i.e. .1, .2, .3, .4, .5). |
|
| AttachmentName.n | The name displayed in the email message for the attached file. This is an optional field and if not provided, the name of the file is used as the attachment name. | |
| AttachmentContentType.n | The content type associated with the attachment. | |
| CharacterSet | The character set in which the email message will be encoded. If this field is not set, the default value of UTF-8 is used. |
|
| AutoTrack | If set to "true" (case insensitive) all links in the HTML content will be made trackable. Otherwise, they will not. If true, any link inside an anchor tag, or image map tag will be marked as trackable. If the tag specifies a "name" attribute, the name will be set as the link name in your activity data. |
|
| UrlAppend | Yes | Use this optional field to specify a string to be appended to each trackable link in your HTML content. This parameter will only be accepted if the AutoTrack option above is set to "true". It can be helpful when used in conjunction with a web analytics system such as Google Analytics to add your campaign Id and other data to each of your links. |
| CustomTrackingDomain | This optional field is used to provide a custom domain name to be used for trackable links and the open tracking URL. You must set a CNAME in your DNS that points to www.messagegears.net. Please test this carefully before using. Example: http://www.mycompany.com (please include the protocol/prefix). |
|
| HeaderName.n | The name of a custom header to be included with the message. You may have up to 5 custom headers each with the appropriate suffix (i.e. .1, .2, .3, .4, .5). |
|
| HeaderValue.n | The value of the header. | |
| CorrelationId | This field allows you to supply your own job id. This Id will be returned with all reporting data (including the real-time data feed) and can make it much easier to match events coming out of MessageGears with the job they belong to in your own system. | |
|
UnsubscribeHeader |
If set to "true" (case insensitive) a header named "List-Unsubscribe" will be added to your message. Otherwise, it will not. This header is used by several ISPs (most notably Gmail) and allows users to click an unsubscribe button in their email reader. You will receive an "unsubscribe" event in your activity data for each click of the unsubscribe button. This is the same event that would result from an unsubscribe link included in your HTML template using the ${Gears.unsubscribe()} Freemarker command. |
|
|
CompressedHtmlTemplate |
Yes | For clients with large HTML templates, it may make sense to send a smaller payload. the CompressedHtmlTemplate will overwrite the HtmlTemplate if it exists, and validates that information is passed in that has been gzipped and then base64 encoded (in that order) |
Programming Examples
REST
Request
https://api.messagegears.net/3.1/WebService
?Action=TransactionalJobSubmit
&AccountId=123456789
&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd
&FromName=MessageGears
&FromAddress=info@messagegears.com
&SubjectLine=Welcome!
&HtmlTemplate=<html>Hello, World!</html>
&RecipientXml=<Recipient><EmailAddress>me@mydomain.com</EmailAddress></Recipient>
Response
<TransactionalJobSubmitResponse>
<RequestId>t23110-a9e77b7c-c980-4ff5-8ede-546fbe0bad66</RequestId>
<Result>REQUEST_SUCCESSFUL</Result>
</TransactionalJobSubmitResponse>
Java SDK
package com.messagegears.sdk.examples;
import com.messagegears.sdk.v3_1.TransactionalJobSubmitResponse;
import com.messagegears.sdk.MessageGearsClient;
import com.messagegears.sdk.MessageGearsProperties;
import com.messagegears.sdk.model.request.TransactionalJobSubmitRequest;
import com.messagegears.sdk.output.ScreenWriter;
public class TransactionalJobSubmit {
public static void main(String[] args) {
// Create the properties object containing the necessary properties
MessageGearsProperties properties = new MessageGearsProperties();
properties.setMyMessageGearsAccountId("place your MessageGears account id here");
properties.setMyMessageGearsApiKey("place your MessageGears api key here");
// Create the main client object
MessageGearsClient client = new MessageGearsClient(properties);
// Create a transactional job request
TransactionalJobSubmitRequest request = new TransactionalJobSubmitRequest();
// Create the XML that represents the email recipient
// (the Recipient and EmailAddress elements are required)
request.setRecipientXml("<Recipient><EmailAddress>" +
"place your email address here" + "</EmailAddress><FirstName>You</FirstName></Recipient>");
// Set the message content
request.setFromName("MessageGears");
request.setFromAddress("no-reply@messagegears.com");
request.setSubjectLine("MessageGears - Reliable Message Delivery");
// Set the HTML part of the message (using some simple personalization)
request.setHtmlTemplate("Hello, ${Recipient.FirstName}!");
// Execute the request
TransactionalJobSubmitResponse response = client.transactionalJobSubmit(request);
// Print the result (success or failure)
ScreenWriter.printResponse(response);
}
}
Comments
Article is closed for comments.