MessageGears FAQs

The MessageGears .NET SDK makes integration seamless. The SDK eliminates the need to write any web services code and enables you to access all of our services using the .NET. It also provides access to Amazon's S3 and SQS services to make it easy to exchange files with MessageGears.

C# sample code is provided with each web service description

NuGet Package Manager

The SDK is available for download from NuGet Gallery.

NuGet Gallery for MessageGears SDK

SDK Downloads

Or you can download and install each DLL by hand with the links below.

MessageGears Code .NET DLL

Amazon AWS DLL

Log4Net DLL

Open Source SDK

We've made the source code to our .NET SDK available to you. You're welcome to write your own code to access our web services natively using our code as a reference.

C# SDK Source Code on GitHub

The MessageGears Java SDK makes integration seamless. The SDK eliminates the need to write any web services code and enables you to access all of our services using the Java language. It also provides access to Amazon’s S3 and SQS services to make it easy to exchange files with MessageGears.

Java Code Examples

Java sample code is provided with each web service description

SDK Download

Latest MessageGears Java SDK

Latest MessageGears Java SDK Source

JavaDoc

JavaDoc

Maven Settings

MessageGears artifacts are available in Maven Central so all you need to do is add us as a dependency in your pom.xml file:

<dependencies>

<dependency>

<groupId>com.messagegears</groupId>

<artifactId>messagegears-java-sdk</artifactId>

<version>3.1.13</version>

</dependency>

</dependencies>

A transactional campaign is a one-to-one campaign which is initiated by some sort of trigger. Examples of transactional email messages would be an email sent as a purchase confirmation, an electronic sales receipt, or a password reset confirmation message. In such cases, the recipient triggers the transactional campaign by performing a specific action.

Each Transactional Campaign in Accelerator contains most of the information necessary to render the message, except the recipient and context data which are provided each time a transactional message is triggered.

Table of Contents

Overview

Settings

Testing Transactional Campaigns

Personalization (Testing & Preview)

Spam Filter Testing

API Examples

Promoting a Transactional Campaign

Analytics

Overview

The Overview page of a Campaign provides a wealth of information about the current setup of the campaign. You can preview using the “Inspect Message Content” button, which takes you to the Personalization page, or by clicking the Send Test.

Additionally, you can view important details of the campaign such as:

Template

The template associated with this campaign is displayed here.

Clicking the template name brings you to the Overview page of that template.

Spam Assassin Score

Displays the score from the Spam Filter testing page.

Clicking the score takes you to this campaign’s Spam Filter testing page.

Approx. Message Size

Displays the size of the template and shared content for this campaign.

Approx. Render Time

Displays the anticipated render time of a single message for this campaign.

Created By

The user who generated the campaign.

Clicking the name will bring you to the User Details page for that individual.

Date Created

The date and time (GMT) when this campaign was generated.

Last Updated By

The user who last made changes to the campaign.

Clicking the name will bring you to the User Details page for that individual.

Date Last Modified

Date and time (GMT) of last campaign edits.

Groups

This corresponds to the User Groups with permissions to access this campaign.

Clicking on a particular group will bring you to a Group Details page.

From the Overview, you can also Promote the campaign. See the "API Examples" guide section for more information about promoting and triggering a Transactional Campaign.

Settings

The Settings page for a Marketing Campaign is where you designate the Template and List for the campaign’s design and recipients.

Name and description can be edited from what was set during the original creation of the campaign, and changes will display on the Overview page. These items are internal and only visible to users, not recipients.

The Category field is meant to be used as a reporting tool, allowing you to categorize and identify groupings of campaigns together. Category is returned with internal reporting data, and can be pulled into campaign content using the personalizable field for Job Category: ${Gears.jobCategory}

In the Template field, you will start typing the name of a Template created in the Content section of Accelerator and select the one you want to send.

Advanced Options

Notification Email Address allows you to provide an address to receive error notifications related to this campaign.

Using the URL Append field, it is possible to add parameters to all links in the campaign, such as Google Analytics UTM strings or other parameters for internal analytics.

Testing Transactional Campaigns

Personalization (Testing & Preview)

On the Personalization page in a Campaign, you can generate a live test of the content on the page in order to test personalization rendering times and results across HTML and text content versions.

Spam Filter Testing

On the Spam Filter page in a Campaign, you can generate and view spam scores associated with the template. This can help to identify content issues which may lead to the campaign emails landing in spam folders rather than recipients’ inboxes. This tool is powered by SpamAssassin, a commonly used spam filter.

API Examples

Using an API request, the recipient and context data can be provided resulting in a single email to a single email address being triggered. The TransactionalCampaignSubmit API requires that a CampaignId be provided with the request, as well as the recipient data used to render and send the message.

Since Transactional Campaigns are triggered by API, the necessary Account ID, Campaign ID, and API Key are all provided on the Transactional Campaign’s “API Examples” page. Additionally, we provide sample code for submitting the API request via REST, Java SDK, or C# SDK.

Read more about the parameters for the TransactionalCampaignSubmit API Here

Note: a Transactional Campaign cannot be triggered until it has been Promoted.

Promoting a Transactional Campaign

Transactional Campaigns are initiated by triggers, but before any transactional messages can be sent the campaign must be initially Promoted. When first Promoting a Transactional Campaign, there will not be any messages triggered to be sent; it merely assigns a campaign ID and makes the campaign available for triggering. Before being Promoted, a Transactional Campaign will not have a Campaign ID to use with the TransactionalCampaignSubmit API.

After being initially Promoted, subsequent changes to content of campaign settings can be made and tested without affecting live triggers. Once the changes have been tested and approved, Promoting the campaign again will push the new content live, and future messages will use the new content.

The Promotion process takes up to 5 minutes to take effect in triggered sends of the campaign, during which time API requests will continue to receive the previously Promoted version.

*Note: Before promoting a Transactional Campaign successfully, the template will need to have a successful preview in the Test->Personalization tab. If there are render errors, please correct your template and retry.

Analytics

Charts on this page reflect daily and monthly statistical trends in engagement with this Transactional Campaign.

TransactionalCampaignSubmit is used to send a single email to a single email address. To send a transactional message based on a campaign, first a Campaign must be created by following the instructions here. The Campaign contains most of the information necessary to render the message, except the recipient data needed to render and send the message. The TransactionalCampaignSubmit API requires that a CampaignId be provided with the request, as well as the recipient data used to render and send the message.

Deprecated Versions

(none)

Required Parameters

Parameter

Personalizable

Description

Action

TransactionalCampaignSubmit

AccountId

The MessageGears account id to which this item belongs.

ApiKey

A secret key only known by you. Keep this key confidential.

CampaignId

The CampaignId of the campaign to be used to render the message. This Id is displayed when creating and promoting a campaign.

RecipientXml

The XML for a single recipient supplied in the prescribed format.

Click here for more information.

Optional Parameters

Parameter

Personalizable

Description

ContextDataXml

This field is used to supply data to the template that is not directly related to the recipient. For example, this field could contain data about weekly airfare specials by city. The template could then select only the fares that originated from the same city as the recipients home. This helps make it easy to create templates with relevant data for each recipient.

Click here for more information.

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.

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.

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

Click here for more information regarding attachments.

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

Click here for more information regarding attachments.

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.

Programming Examples

REST

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=TransactionalCampaignSubmit

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&CampaignId=22222222

&RecipientXml=<Recipient><EmailAddress>[email protected]</EmailAddress></Recipient>

Response

<TransactionalJobSubmitResponse>

<RequestId>t23110-a9e77b7c-c980-4ff5-8ede-546fbe0bad66</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

</TransactionalJobSubmitResponse>

Java SDK

Click here for more information on using the MessageGears 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 final String MY_EMAIL_ADDRESS = "place your email address here";

public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void main(String[] args) {

// Create the properties object containing the necessary properties

MessageGearsProperties properties = new MessageGearsProperties();

properties.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);

properties.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

// Create the main client object

MessageGearsClient client = new MessageGearsClient(properties);

// Create a transactional job request

TransactionalCampaignSubmitRequest request = new TransactionalCampaignSubmitRequest();

// Create the XML that represents the email recipient

// (the Recipient and EmailAddress elements are required)

request.setRecipientXml("<Recipient><EmailAddress>" +

MY_EMAIL_ADDRESS + "</EmailAddress><FirstName>You</FirstName></Recipient>");

// Set the campaign id

request.setCampaignId(12345);

// Execute the request

TransactionalJobSubmitResponse response = client.transactionalCampaignSubmit(request);

// Print the result (success or failure)

ScreenWriter.printResponse(response);

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;

using MessageGears;

using MessageGears.Model;

using MessageGears.Model.Generated;

namespace MessageGears.Sample

{

public class TransactionalSample

{

// Replace this value with your email address

public const String MY_EMAIL_ADDRESS = "place your email address here";

public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void Main ()

{

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;

props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

// Create the main client object

MessageGearsClient client = new MessageGearsClient(props);

// Create a transactional campaign request

TransactionalCampaignSubmitRequest request = new TransactionalCampaignSubmitRequest();

// Create the XML that represents the email recipient

// (the Recipient and EmailAddress elements are required)

request.RecipientXml = "<Recipient><EmailAddress>" +

MY_EMAIL_ADDRESS + "</EmailAddress><FirstName>John</FirstName></Recipient>";

// Set the campaign id

request.CampaignId = "12345";

// Execute the request

TransactionalJobSubmitResponse response = client.TransactionalCampaignSubmit(request);

// Print the result (success or failure)

client.PrintResponse(response);

}

}

}

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.

Click here for more information.

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.

Click here for more information regarding the use of OnBehalfOf.

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

Click here for more information regarding attachments.

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

Click here for more information regarding attachments.

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.

Click here for a full list of available character sets.

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.

Click here for more information.

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.

Click here for more information.

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

Click here for more information.

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

Click here for more information regarding custom headers.

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.

Click here for more information.

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

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=TransactionalJobSubmit

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&FromName=MessageGears

&[email protected]

&SubjectLine=Welcome!

&HtmlTemplate=<html>Hello, World!</html>

&RecipientXml=<Recipient><EmailAddress>[email protected]</EmailAddress></Recipient>

Response

<TransactionalJobSubmitResponse>

<RequestId>t23110-a9e77b7c-c980-4ff5-8ede-546fbe0bad66</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

</TransactionalJobSubmitResponse>

Java SDK

Click here for more information on using the MessageGears 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("[email protected]");

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);

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

MessageGears' campaign management software integrates directly with Snowflake using the Snowflake JDBC driver that is included with MessageGears. With this seamless integration, clients can directly access their Snowflake data regardless of where the MessageGears software is hosted, including AWS and Azure. This integration allows users to access their Snowflake data natively with MessageGears' audience builder, content personalization, and orchestration features without replication, data mapping or synchronization.

Snowflake Integration Setup

Have an Accelerator System Administrator connect to the Snowflake instance using the Accelerator Database connection portal.

Select "Snowflake" as your Database Type.

Enter a unique and meaningful name for the database connection.

Enter Account Name and Port. This is the account and region name as defined by Snowflake.

Enter a User Name and Password that will allow Accelerator to connect to the Snowflake instance. If the user does not have a password associated with it, you may leave the password field blank. This is the primary way to apply connectivity and access permissions to Accelerator to limit what data it has access too. The user is also the preferred place for Snowflake users to apply warehouse permissions.

Optionally, make this the default connection for the application so that users are able to have this connection used by default in the various locations within Accelerator.

Further define the Connection Defaults. Defaults are settings such as a Default Table or Default Schema that allow an Admin to make the experience in Accelerator more hassle free by dictating the default areas where an Accelerator user will access data. The currently supported defaults are:

Table

Schema

Database

Warehouse

Unique Id Column

Preference Column

Email Column

Push App

Push Address

Push Service

Define custom Datasource Properties. Datasource Properties are optional parameters that Accelerator will append to the connection string.

The Audience > Database Connections page is where the foundations for managing audiences are established. Database Administrators can establish, test, change, or delete database server connections as needed, and all connected databases will be listed on the Connections page. Database Connections are used to retrieve and build recipient mailing lists, extract relevant context data to include with your templates, and map event results directly back to your database.

You can define as many connections as needed, create read or write connections based on user permissions, indicate a default database for the Account, and connect to a variety of database types.

Adding a Database Connection

Selecting the Add Connection button opens a page to fill out with details and credentials related to the database. Accelerator supports any database with a JDBC connector, including, but not limited to, the following: DB2, MySQL, Oracle, PostgreSQL, Amazon Redshift, Microsoft SQL Server, Google BigQuery, Apache Hadoop, Snowflake, and Teradata. Salesforce integration is also supported.

To add a database connection:

Note: You must enter a Name, Database Type, Host Name, and Port number for each connection. All other fields are optional.

Enter a unique and meaningful Name for the new data warehouse.

Select the appropriate Database Type.

Enter the Host Name of the database server.

Enter the Port number associated with the server.

(optional) Enter the name of default database.

(optional) Enter the User ID and Password.

(optional) Click Add Property to indicate property names and values that you want to automatically associate with this connection.

Click Save.

Managing Database Connection Properties

Clicking the name of a particular database from the Database Connections list opens the details of that connection, including the properties in place for that database as well as all queries using that database.

Using the Actions menu, it’s possible to Duplicate, Archive, Edit, or Delete a Database Connection.

A database with associated queries cannot be deleted. Queries associated with a database must be deleted before the database itself can be deleted.

MessageGears uses an open source Web Template Language called Freemarker to enable personalization of the email content including the HTML, Subject Line, Text, etc. FreeMarker allows you to reference the data provided in your Recipient XML in order to personalize your email content.

Table of Contents

Simple Personalization

Click Tracking

Unsubscribe Links

Hosted Email Content

Looping

Sorting

Formatting Numbers, Strings, and Dates

Localization

Reference Resources

Complete FreeMarker reference: http://freemarker.org

Simple Personalization

MessageGears allows you to personalize your email content (HTML, Text, Subject Line, etc.). You simply reference items, by name, from your recipient XML data.

Recipient XML

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

<FirstName>Joe<FirstName>

<MyCustomField>XYZ</MyCustomField>

<Recipient>

HTML/Text Template

Rendered Message

Hello, ${Recipient.FirstName}!

Hello, Joe!

${Recipient.MyCustomField}

XYZ

Click Tracking

You can automatically make all links in a message trackable by setting the "autotrack" parameter to "true" in your API call.

HTML/Text Template

Click <a href="${Gears.track("http://www.myhomepage.com", "Home Page")}">here</a> to go to our home page.

The first parameter is the target URL. The second parameter is optional and creates a label that is also recorded as part of the click activity.

Unsubscribe Links

You can optionally allow MessageGears to manage un-subscription data for you. When a user clicks on an unsubscribe link they will be prompted to confirm their opt-out. If they confirm, you will be sent an "unsubscribe" event in your activity data.

HTML/Text Template

Click <a href="${Gears.unsubscribe()}">here</a> to unsubscribe.

Hosted Email Content

Microsites are hosted versions of email messages. They are typically used to allow the email recipient to launch and view their email message in a browser if they are having difficulty viewing it in their email reader. When a microsite link is clicked in a message, a browser window will open and the fully personalized version of the HTML content of their email message will be rendered as a web page.

HTML/Text Template

Click <a href="${Gears.microsite()}">here</a> if you are having trouble viewing this message.

Looping

Recipient XML

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

<FirstName>Joe</FirstName>

<Order>

<OrderNumber>987654321</OrderNumber>

<Item>

<Sku>123456</Sku>

<Price>25</Price>

<Qty>1</Qty>

<Desc>Hammer</Desc>

</Item>

<Item>

<Sku>987654</Sku>

<Price>32</Price>

<Qty>2</Qty>

<Desc>Saw</Desc>

</Item>

</Order>

</Recipient>

HTML/Text Template

Result

Hello, ${Recipient.FirstName}!

Thank you for your recent order.

Order Number: ${Recipient.Order.OrderNumber}

<#list Recipient.Order.Item as item>

Item: ${item.Sku}

Price ${item.Price}

Qty: ${item.Qty}

</#list>

Hello, Joe!

Thank you for your recent order.

Order Number: 987654321

Item: 123456

Price 25

Qty: 1

Item: 987654

Price 32

Qty: 2

Sorting

Recipient XML

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

<FirstName>Joe</FirstName>

<Order>

<OrderNumber>987654321</OrderNumber>

<Item>

<Sku>987654</Sku>

<Price>32</Price>

<Qty>2</Qty>

<Desc>Saw</Desc>

</Item>

<Item>

<Sku>123456</Sku>

<Price>25</Price>

<Qty>1</Qty>

<Desc>Hammer</Desc>

</Item>

</Order>

</Recipient>

HTML/Text Template

Result

<#list Recipient.Order.Item?sort_by("Desc") as item>

Desc: ${item.Desc}

Item: ${item.Sku}

Price ${item.Price}

Qty: ${item.Qty}

</#list>

Desc: Hammer

Item: 123456

Price 25

Qty: 1

Desc: Saw

Item: 987654

Price 32

Qty: 2

<#list Recipient.Order.Item?sort_by("number(Price)") as item>

Desc: ${item.Desc}

Item: ${item.Sku}

Price ${item.Price}

Qty: ${item.Qty}

</#list>

Desc: Hammer

Item: 123456

Price 25

Qty: 1

Desc: Saw

Item: 987654

Price 32

Qty: 2

Formatting Numbers, Strings, and Dates

Recipient XML

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

<Date>2010-01-01</Date>

<Number>200.257</Number>

<String>ABCxyz</String>

</Recipient>

HTML/Text Template

Result

${Recipient.Date}

2010-01-01

${Recipient.Date?date("yyyy-MM-dd")}

Jan 1, 2010

${Recipient.Date?date("yyyy-MM-dd")?string.short}

1/1/10

${Recipient.Date?date("yyyy-MM-dd")?string.medium}

Jan 1, 2010

${Recipient.Date?date("yyyy-MM-dd")?string.long}

January 1, 2010

${Recipient.Date?date("yyyy-MM-dd")?string.full}

Friday, January 1, 2010

${Recipient.Number}

200.257

${Recipient.Number?number}

200.257

${Recipient.Number?number?string.currency}

$200.26

${Recipient.Number?number?string.percent}

20,026\%

${Recipient.Number?number?round}

200

${Recipient.String}

ABCxyz

${Recipient.String?substring(1,4)}

BCx

${Recipient.String?upper_case}

ABCXYZ

${Recipient.String?capitalize}

Abcxyz

Localization

Using the localization features requires you to set the locale variable. The local variable consists of the ISO-639 two character language code (lower case), followed by the ISO-3166 two character country code (upper case) in the following format: xx_XX. For example, UK English would be "en_UK".

Recipient XML

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

<Locale>fr_FR</Locale>

<Date>2010-01-01</Date>

<Number>200.257</Number>

</Recipient>

HTML/Text Template

Result

<#setting locale="Recipient.Locale">

${Recipient.Date?date("yyyy-MM-dd")?string.full}

vendredi 1 janvier 2010

<#setting locale="us_EN">

${Recipient.Date?date("yyyy-MM-dd")?string.full}

Friday, January 1, 2010

FreeMarker Reference Resources

Directives/Command Syntax

String Functions

Date Functions

Numeric Functions

XML Processing

Optionally, you may also use the Apache Velocity templating language.

MessageGears enables clients to work directly off of existing data schemas, requiring no data mapping or additional synchronization. This can be done through direct SQL queries utilizing the native SQL functionality of each distinct database, allowing users to leverage the power of their internal databases directly.

However, in many cases a small amount of foundational work can enable the marketing team to fully leverage the functionality of our Drag & Drop Audience Builder, providing autonomy to the Marketing team. Below are a few recommendations for developing a client view that best supports an independent marketing team.

Member Profile Attributes

Customer Identifier

Used as the RecipientId within our platform. This value is returned with each activity generated by our platform.

customer_id (integer)

Opt-in / Suppression Attributes

Used to identify the status of each recipient, to avoid mailing invalid or unsubscribed users.

opt_in_status (boolean)

opt_in_timestamp (timestamp)

opt_out_timestamp (timestamp)

invalid_email (timestamp)

Engagement Metrics

Used to perform segmentation of recipients based on engagement date / rates. Important for deliverability monitoring and segmentation.

last_open (timestamp)

last_click (timestamp)

last_mailing (timestamp)

Localization Fields

Used to localize message content and optimize delivery windows.

locale (varchar(20))

user_timezone (varchar(20))

Contact Fields & Preferences

Used to identify which contact channels are available to each recipient, and set a designated preferred contact channel for marketing or transactional alerts.

email_address (varchar(256))

sms_address (varchar(256))

device_id (varchar(256))

device_service (varchar(256))

channel_preference (varchar(256))

Additional Fields

There might be additional fields that are vital to support your marketing team's day to day activities. If you want to consult with us about the best solution for your needs, please feel free to open up a ticket with Support or drop as a note at [email protected] and someone from our Solutions team will be happy to help.

Background

In many enterprise organizations, it is common to use a Single Sign-On (SSO) provider (such as Okta or Google) to manage application access from one central facility. In order to support this, MessageGears has built Accelerator to comply with a common standard for implementing SSO, SAML 2.0. This document explains the basics of how SSO works with MessageGears software and how to set up an instance of Accelerator to use SSO.

Before we get into the details of SSO, let's first cover how MessageGears handles authentication without SSO. MessageGears has two primary components of software:

Accelerator is the on-premise software that is installed behind your firewall or in your private cloud next to your marketing database.

There is also a MessageGears' Cloud component which is where we render and send your messages to the various ISPs.

In a typical authentication scenario, all users (and their roles) are stored in the MessageGears cloud. So, when you log into Accelerator, it checks Cloud to see if the username is valid and what roles that user has.

When you enable SSO for your instance of Accelerator, Accelerator will instead call your Identity Provider (IdP) to determine if the user is a valid user. Accelerator itself will store the roles of the various users, so part of the set-up of SSO will be to create users that are local to Accelerator. It is recommended that you create all new local users after enabling SSO (rather than trying to migrate any of the users in Cloud to the local Accelerator instance). Please contact Client Success for more details.

Once the Accelerator administrative setup is complete and the local Accelerator users have been properly created, the login flow will look like this (using Okta as the example IdP).

Set up SSO with Google / G Suite

In the case where SAML is having issues, there will continue to be a separate URL where you can login to Accelerator (using Cloud to authenticate the user) that we'll cover at the end of this document.

Setup

Both Okta and Google are currently the supported identity providers; however, our SAML implementation may be compatible with others as well. If you want us to help you check compatibility with your identity provider, please let us know by contacting the support team at [email protected].

Set up SSO with Okta

Using Single Sign On

Once the SAML has been setup, users will access Accelerator using the typical URL and they will follow the flow outlined below.

The user tries to access a page within an instance of Accelerator.

Accelerator sends a redirect message back to the user’s browser and includes the URL that the user was trying to access.

The user’s browser forwards the redirect on to Okta / Google.

If the user doesn’t have a valid session, the corresponding login page is displayed.

Once the user logs in, Okta / Google generates the SAML Assertion for that particular user.

When the SAML Assertion reaches Accelerator, Accelerator looks to see if the Username is valid and unlocked. The user is logged in at that point.

Finally, Accelerator determines whether the user has access to the resource defined by the URL and if so, serves the page.

Accessing Accelerator via a Backdoor

In order to facilitate access to Accelerator if there are problems with configuration or communication with the IdP, there is an additional URL that can be used to access Accelerator using a Cloud user.

http://<your-accelerator-hostname>:<your-accelerator-port>/loginCloud.html

NOTE: It is important that you keep changes to audiences/templates/campaigns/etc. to a minimum. This feature is designed to make Administrative changes and halt campaigns in emergency situations. This access should not be used for regular functionality (as it will not be associated with a local user).

Setting up a white-labeled domain removes all DNS references to the MessageGears service, so that messages appear to originate from your company’s domain. This is beneficial for consistent branding of your emails, as well as for inbox placement and email authentication.

Table of Contents

Custom Tracking Domain

DNS record

independent implementation (Portal access needed)

Custom Signing Domain

DNS records

best practices

contacting Support for implementation

Dedicated IPs

eligibility requirements

Custom Tracking Domain

A custom tracking domain allows you to change the domain of the AutoTracking URL in your email content. AutoTrack URLs are redirects which route the clicker briefly through MessageGears before landing them on the target page, allowing MessageGears to identify that unique click and the recipient who made it.

Setting up a custom tracking domain for individual accounts is a simple process and the result is that the links in your email content will be white-labeled with your website's URL. This is an alternative to the messagegears.net domain that displays by default in click-tracked links. Having your own domain present in those URLs can help to reinforce the legitimacy of the links and ensure consistent branding across your email content.

To set up your custom tracking domain, you must first select a unique subdomain. This subdomain will be visible in the link that recipients click from your email content before they are redirected to the resulting web page. Here are some suggestions for tracking subdomains to use:

trk.yourdomain.com

link.yourdomain.com

go.yourdomain.com

www2.yourdomain.com

Once you've decided on a subdomain, you will need to create the following CNAME record in your DNS:

Subdomain

Type

Value

trk.yourdomain.com

CNAME

www.messagegears.net.

Once the CNAME record is in place, it's possible to make the tracking domain change within Portal:

Navigate to Account

Click to open a specific account

Edit Account Settings

Enter the subdomain you've selected in the Tracking Domain box and Save the change

Custom Signing Domain

The next step in setting up a white-labeled domain for use with MessageGears is to set up DNS records designating a custom signing domain.

Use a Subdomain

We require you to select a subdomain to be used for marketing related messages sent from the MessageGears platform. Contact MessageGears support for the necessary records for SPF and DKIM to implement on your chosen subdomain.

We also highly recommend implementing SPF and DKIM on the top-level domain as well any domains used with From Addresses when sending via MessageGears.

Why place records on a subdomain and when to add records on the top-level domain (TLD)

The reason we suggest using a subdomain for the custom signing domain is related to organization and reputation. A specific subdomain for MessageGears records helps to keep sending reputation for your marketing and transactional emails (sent through MessageGears) separate from the reputation of the top-level domain tied to your regular one-to-one emails sent through your own mail server.

However, implementing email authentication DNS records for your TLD may still be important for best domain alignment across all receiving servers, particularly when DMARC is in place.

Sometimes deprecated or less popular email authentication methods are still checked by a receiving system, so having these records in place for your TLD will cover these methods as well. Examples include sender-id and domainkeys, which are less widely used than SPF and DKIM, but they may still occasionally appear in email headers.

Covering all of the bases by having MessageGears email authentication records in place on both a designated subdomain and the top-level domain helps to ensure best deliverability across all recipients.

Custom signing domain implementation - contact Support to complete!

In order for your emails to start being signed by your new custom signing domain, you'll need to contact Support to put this into effect. Support will verify the DNS records are in place, then provide an ETA on when the custom signing domain provisioning will be complete. This usually takes about 3-5 business days.

When writing in to Support, please be sure to providing the following details:

Customer ID

Account ID(s) - indicate whether all accounts for the Customer are getting the custom signing domain (common), or what specific account ID(s) the custom signing domain should be applied to

Custom Signing Domain - be sure to include the subdomain you've chosen

Dynamic Signing Domain implementation - contact Support to complete!

In order for your emails to start being signed by your new dynamic signing domain, you'll need to contact Support to put this into effect. Support will verify the DNS records are in place, then provide an ETA on when the dynamic signing domain provisioning will be complete. This usually takes about 3-5 business days.

When writing in to Support, please be sure to providing the following details:

Customer ID

From domain, Custom signing Domain (subdomain), Tracking domain

Our new dynamic signing domain feature is setup at the organization/customer level, which automatically populates the SPF/DKIM domains (signing domain) and tracking domain based on the from domain used. This will ensure domain alignment and white-labeling across your emails. Additionally, this will ensure DMARC compliance, for those who have a policy in place.

Example:

From domain: example.com

SPF: mg.example.com

DKIM: mg.example.com

Custom tracking domain: link.example.com

Please note, that this feature is applied at the organization/customer level, so any account under the org that uses the from domain would automatically sign on the associated SPF/DKIM and tracking domains.

Dedicated IPs

Dedicated IPs are unique Internet addresses dedicated exclusively to emails sent through your MessageGears account. Generally accounts send through a randomized set of shared IPs used by many other customers, which means the reputation of your sending IPs is shared by other MessageGears customers. The main benefit to having dedicated IPs for your sending would be more control over the reputation of those IPs, which only your account will send through. This also allows you to have a specific set of IPs to provide to recipients who may want to whitelist your sends to ensure delivery to their inboxes.

The primary criteria for dedicated IPs to send through with MessageGears is sending volume. If you're currently sending at least 1 million emails/month and are interested in dedicated IPs, please contact Support for more information and for evaluation on whether your account is qualified for them.

Example URL

Protocol

http://www.mycomany.com/document.pdf

https://www.mycompany.com/document.pdf

http/https

Accessing files in this manner requires you to make the files accessible over the Internet via a web server. Use this method only when the files/content are not of a secure nature.

Example URL

Protocol

http://user:[email protected]/document.pdf

https://user:[email protected]/document.pdf

http/https with Basic Authentication

Using Basic Authentication, you can make your files accessible over the Internet only to those who know the correct username and password. The credentials are passed in as part of the URL. It is recommended that only the HTTPS protocol be used with this method so the credentials are protected during the request transmission.

Example URL

Protocol

s3://[bucket-name]/[file-key]

s3://mycompany-bucket/document.pdf

Amazon S3

For those that have an Amazon S3 account, you can specify the location of the file by passing in the name of the bucket followed by the file name (or key) of the file. The file is stored in your S3 account and privacy is strictly under your control.

The MessageGears Amazon S3 canonical user id for our US account is: 2dd8e53f1a8e4dfe3a6893d1229635b4915661d95f5283df75215779ce462819

You will need to make sure to grant "read" access to the MessageGears Amazon account so we will be able to retrieve the file.

Audiences

An Audience is a list of recipients that will be mailed content in a campaign that can be segmented and personalized by the user. Audiences are created in one of 3 ways:

Drag and Drop Audience creation empowers non-technical marketers to specify the target audience they want to communicate with by selecting recipient attributes and easily incorporating additional logic like AND, OR and so on

Manual SQL Creation is for the IT professional or Data specialist who works with the Marketing team to create detailed audiences using knowledge of their data environment

Uploading recipients from an API Endpoint is available for users with Audiences in online file systems (such as Amazon S3 files) accessible via URL

Each section below will cover one of these steps in detail. For additional detail on using audiences to send campaigns, see our article on Campaigns.

Creating an Audience via Drag and Drop SQL creation is an easy yet powerful way to create and segment your audience, all without manually building any SQL. There are 3 steps in creating a drag and drop audience:

Selecting a Data Source

Specifying the Audience Target

Adding Personalization Attributes

1. Selecting a Data Source

The first step in creating a drag and drop audience is to select the data source where the information for the audience resides. The data sources will have some or all of the following fields:

(Note: Each data source will need to be previously configured from the Admin section)

Connection

This is the data connection that has been created in the admin section of your account

Database Catalog

Additional information regarding your connection. Check with an administrator if you are unsure where your data is located

Database Schema

Table

Email Address

This field is what Accelerator will use to try and send the email with. Make sure that your field contains valid email addresses

Unique ID

This is a field of unique entries (such as Customer ID or account ID) that signifies each unique recipient

2. Specifying the Audience Target

Now that the data source has been defined, the next step is to segment the audience using Accelerator’s Drag and Drop SQL builder. Add rules to add on individual statements and use the groups to build nested logic. For instance, this screenshot segments the audience down to recipients whose gender is male and whose primary residence is NOT Florida OR Georgia

Data Type

Supported Operands

Numerical

Less than

Less than or equal to

Greater than

Greater than or equal to

Is between

Is not between

Equal to

Not equal to

Is null

Is not null

String

Begins with

Doesn’t begins with

Contains

Doesn’t contain

Ends with

Doesn’t end with

Is empty

Is not empty

Equal to

Not equal to

Is null

Is not null

Date (e.g. DATE FORMAT HERE)

Before

Before or On

After

After or On

Is between

Is not between

Equal to

Not equal to

Is null

Is not null

Boolean (e.g. 1 or 0)

True or False

3. Adding Personalization Attributes

Personalization Attributes are the fields in your data source that will be used within the email content and sent to the user. Personalization attributes exist outside of segmentation criteria so users can use sensitive data behind their firewall to segment the audience, while pushing non-sensitive customer information to the cloud for email. In this example, we have used the offers the customer has redeemed to help segment our audience, but are passing forward their company and state to be used in the content of the email they receive:

The personalization attributes included for an audience are the only fields that leave your secure data environment and are passed up to Messagegears’ cloud. If you choose not to include any additional information in personalization attributes, no additional information will leave your firewall. Because all of the personalization variables selected will be available for reference in any campaigns using this audience, it is best practice to only select the variables that will be directly referenced in the email. Selecting a large amount of Personalization Attributes may slow email rendering times.

Creating an audience through manual SQL creation gives the user with enhanced knowledge about his or her data environment complete control over audience segmentation. A major advantage to this method is the flexibility the user has in joining data across different tables or views into the same audience. Additionally, the user has the ability to customize the audience based on content within an email template. See below for an example, or check out our primer on using FreeMarker to customize your email content.

There are two primary steps to creating an audience using SQL:

Create the SQL Query

Set Launch Variables (Optional)

1. Creating the SQL Query

To create a SQL audience, simply type your SQL statement into the query editor and save. Be sure that your select statement either directly references or aliases the field names of ‘EmailAddress’ (and ‘RecipientID’, if used), as our Cloud application will use these values when rendering and sending email downstream.

2. Setting Launch Variables (Optional)

Launch variables aide the marketer in targeting a campaign to a specific audience at the time of launching. Launch variables are freemarker variables inserted into the SQL statement that are given names, labels, and default values that the marketer can change on the campaign screen. In this example, the ‘HotelCity’ has been configured within the query to be the variable within the WHERE clause, with the Default value being ‘Atlanta’, and some additional help text for the marketer:

Now, let’s look at a campaign that uses this audience to see how this launch variable might show up to the marketer:

Notice that the marketer can now alter the Launch Variable to dynamically change the WHERE clause in their audience SQL query, and the help text we typed earlier helps them understand what the variable is and how it should be used. This cuts down the need to constantly change audience queries and makes for a more robust audience to be used in Marketing Campaigns.

If your Audience data sits at the end of an API endpoint, it is an easy two-step process to ingest and configure that data for use in marketing campaigns:

Configure the API Endpoint

Set Launch Variables (optional)

1. Configuring the API Endpoint

Setting the endpoint for your API audience is oftentimes as simple as just pasting in the URL and hitting ‘save’. In this example, a username and password (for basic authentication) have been added, to allow for secure data storage of audience information:

2. Setting Launch Variables

Launch variables aide the marketer in targeting a campaign to a specific audience at the time of launching. Launch variables are freemarker variables inserted into the API endpoint that are given names, labels, and default values that the marketer can change on the campaign screen. In this example, several pieces of the URL have been dynamically configured to be any value a marketer has entered:

Notice that the marketer can now alter the Launch Variable to dynamically change the URL endpoint for their API audience, and the help text we typed earlier helps them understand what the variable is and how it should be used. This cuts down the need to constantly change audience queries and makes for a more robust audience to be used in Marketing Campaigns.

This API call is used to create a account. The new account inherits the properties of the account used to create it (the one making the API call).

Deprecated Versions

(none)

Required Parameters

Parameter

Description

Action

CreateAccount

AccountId

The MessageGears account id to which this item belongs.

ApiKey

A secret key only known by you. Keep this key confidential.

Name

The name of the account to be created.

Optional Parameters

Parameter

Description

AutoTrack

Change the default value for all jobs sent through this account to “true” or “false”

UrlAppend

Change the default string to be appended to all tracking links for this account

CustomTrackingDomain

Change the default domain to be used for all tracking URLs (click, open, unsubscribe)

Programming Examples

REST

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=CreateAccount

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&Name=Quality Assurance Account

Response

<CreateAccountResponse>

<RequestId>e311-89fff13f-9866-4e5d-856f-7bd01cb612d3</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

<Account>

<Id>70916599</Id>

<ApiKey>4a3140d4ae7449b3832aae7449b383</ApiKey>

</Account>

</CreateAccountResponse>

Java SDK

Click here for more information on using the MessageGears Java SDK

package com.messagegears.examples;

import com.messagegears.sdk.MessageGearsClient;

import com.messagegears.sdk.MessageGearsProperties;

import com.messagegears.sdk.model.request.CreateAccountRequest;

import com.messagegears.sdk.output.ScreenWriter;

import com.messagegears.sdk.v3_1.CreateAccountResponse;

public class CreateAccount {

public static final String MY_EMAIL_ADDRESS = "place your email address here";

public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void main(String[] args) {

// Create the properties object containing the necessary properties

MessageGearsProperties properties = new MessageGearsProperties();

properties.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);

properties.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

// Create the main client object

MessageGearsClient client = new MessageGearsClient(properties);

// Create a bulk campaign request

CreateAccountRequest request = new CreateAccountRequest();

// Set the URL where the recipient XML file can be retrieved

request.setName("QA Account");

// Set auto link tracking to true

request.setAutoTrack(true);

// Execute the request

CreateAccountResponse response = client.createAccount(request);

// Print the result (success or failure)

ScreenWriter.printResponse(response);

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;

using MessageGears;

using MessageGears.Model;

using MessageGears.Model.Generated;

namespace MessageGears.Sample

{

public class CreateAccountSample

{

// Replace this value with your email address

public const String MY_EMAIL_ADDRESS = "place your email address here";

public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void Main ()

{

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;

props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

// Create the main client object

MessageGearsClient client = new MessageGearsClient(props);

// Create a bulk campaign request

CreateAccountRequest request = new CreateAccountRequest();

// Set the Account Name

request.Name = "QA Account";

// Set the default for Auto Tracking of links

request.AutoTrack = false;

// Execute the request

CreateAccountResponse response = client.CreateAccount(request);

// Print the result (success or failure)

Console.WriteLine("New Account ID: " + response.Account.Id);

client.PrintResponse(response);

}

}

}

This API call is used to modify account details related to link tracking on the account.

Deprecated Versions

(none)

Required Parameters

Parameter

Description

Action

UpdateAccount

AccountId

The MessageGears account id to which this item belongs.

ApiKey

A secret key only known by you. Keep this key confidential.

Id

The ID of the account to be updated.

Optional Parameters

Parameter

Description

Name

Change the name of the account

AutoTrack

Change the default value for all jobs sent through this account to “true” or “false”

UrlAppend

Change the default string to be appended to all tracking links for this account

CustomTrackingDomain

Change the default domain to be used for all tracking URLs (click, open, unsubscribe

Programming Examples

REST

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=UpdateAccount

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&Id=70916599

&Name=Quality Assurance Account

Response

<UpdateAccountResponse>

<RequestId>e311-89fff13f-9866-4e5d-856f-7bd01cb612d3</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

</UpdateAccountResponse>

Java SDK

Click here for more information on using the MessageGears Java SDK

package com.messagegears.examples;

import com.messagegears.sdk.MessageGearsClient;

import com.messagegears.sdk.MessageGearsProperties;

import com.messagegears.sdk.model.request.UpdateAccountRequest;

import com.messagegears.sdk.output.ScreenWriter;

import com.messagegears.sdk.v3_1.UpdateAccountResponse;

public class UpdateAccount {

public static final String MY_EMAIL_ADDRESS = "place your email address here";

public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void main(String[] args) {

// Update the properties object containing the necessary properties

MessageGearsProperties properties = new MessageGearsProperties();

properties.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);

properties.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

// Update the main client object

MessageGearsClient client = new MessageGearsClient(properties);

// Update a bulk campaign request

UpdateAccountRequest request = new UpdateAccountRequest();

// Set the URL where the recipient XML file can be retrieved

request.setName("QA Account");

// Set auto link tracking to true

request.setAutoTrack(true);

// Execute the request

UpdateAccountResponse response = client.updateAccount(request);

// Print the result (success or failure)

ScreenWriter.printResponse(response);

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;

using MessageGears;

using MessageGears.Model;

using MessageGears.Model.Generated;

namespace MessageGears.Sample

{

public class UpdateAccountSample

{

// Replace this value with your email address

public const String MY_EMAIL_ADDRESS = "place your email address here";

public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void Main ()

{

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;

props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

// Create the main client object

MessageGearsClient client = new MessageGearsClient(props);

// Create a bulk campaign request

UpdateAccountRequest request = new UpdateAccountRequest();

// Set the Account Name

request.Name = "QA Account";

// Set the default for Auto Tracking of links

request.AutoTrack = false;

// Execute the request

UpdateAccountResponse response = client.UpdateAccount(request);

// Print the result (success or failure)

client.PrintResponse(response);

}

}

}

A Campaign Trigger is a custom SQL action set to be performed in relation to a campaign launch. This can prevent replication of data in your database by performing actions automatically, such as changing or updating database fields, or simply record campaign launches to empower your internal campaign tracking and reporting.

Campaign Triggers are used within Marketing Campaigns, where users can identify triggers as Pre-Campaign or Post-Campaign. You won't need to select whether a trigger is Pre- or Post-Campaign until applying the trigger to a campaign in the Campaign Settings section, though creating the Trigger Actions with the end goal in mind is helpful.

The following data elements are available to use in Campaign Triggers, though certain campaign data won’t be available to use in Pre-Campaign triggers, such as recipient count or request ID, as these values are not defined until the campaign has been launched successfully.

Template Metadata

Element Name

Type

templateId

Integer

templateName

String

templateDescription

String

fromAddress

String

fromName

String

subjectLine

String

replyToAddress

String

approxTemplateSize

Long

spamAssassinScore

Double

charSet

String

Job Metadata

Element Name

Type

campaignId

Integer

campaignName

String

campaignDescription

String

accountId

Integer

accountName

String

ipSelector

String

jobId

Integer

notificationEmailAddress

String

category

String

urlAppend

String

jobStatus

String

error

Boolean

errorMessage

String

firstRecipientXml

String

messageGearsRequestId

String

recipientCount

Long

s3RecipientDataUrl

String

startTime

Date

variantName

String

Managing Campaign Triggers

On the main page is a list of Campaign Triggers which can be searched and sorted. To drill into a specific Trigger, click its name.

Within each individual Campaign Trigger is information about its creation, and a list of the Actions related to the Campaign Trigger. To add a new Action, select the Add Action button.

To test, edit, duplicate, or delete individual Actions, click the name of the Action. The testing function is found below of the details and SQL query.

When a Trigger contains multiple Actions, the actions are performed in a sequential order. Since Actions occur sequentially, arrange them in the order you want the SQL actions to take place using the up/down arrows placed on the left side of each item:

Example Use Case:Save Campaign Details to your Database

A commonly used Campaign Trigger is to add each send of a campaign to a database, including details such as IDs and recipient counts. In a case like this, you’ll want to use this Trigger as a Post-Campaign Trigger, which are best used when working with campaign details.

To the left is SQL example of a Trigger Action query adding a row to the database, including details such as the ID, timestamp, recipient count, and other unique campaign details.

Note that a pre-campaign trigger won’t be able to include the request ID or number of recipients, since those details won’t be available yet. Once a campaign is sent, those details will be available for inclusion in SQL queries.

TheSample SQL image below is the same Trigger Action SQL from above, run through the “Preview SQL” function. You can see placeholder values are populating the FreeMarker portion of the query, indicating what sort of values to expect based on the campaign this Action is triggered by.

Note that the myschema.campaign_history table is NOT defined by Accelerator. The format of this table is defined and maintained by your team, and FreeMarker is used to populate the appropriate fields. Other schema or table structures may be used as required by your team.

URL Data Sources allow you to serve recipient or context data using a URL rather than a query to a database. The URL can be anything from a static file to a web-service application that dynamically returns data based on URL parameters. Acceptable data types include XML and CSV. Zip and gzip compression are also supported. Ultimately as long as Accelerator can access the endpoint, you can leverage the URL as a data source.

As a reminder, Recipient data type sources will show a list of email addresses and other recipient-level fields for use as Recipient data in Marketing Campaigns, while Context data type sources will retrieve unstructured data that may be used during the template merge process.

Adding a URL Data Source

Note: You must enter a Name and URL for each data source. All other fields are optional.

Enter a unique and meaningful Name for the new data source.

Enter the URL associated with the data source.

(optional) Enter the Username and Password if the URL requires credentials to access.

(optional) Click the Add Criteria button to indicate criteria names, labels, values, and help text that you want to associate with this source.

Name is the Freemarker substitution name of your criteria.

Label is the natural name you want to reference.

Default Value is the content that populates for a personalized field if custom data is unavailable.

Help Text is an extended description of your label.

Click Save.

The Real-Time Data Feed refers to specific activity taking place in relation to a message sent through MessageGears. In the Admin > Real-Time Data Feed section of Accelerator, users can customize actions to occur when a specific Activity occurs. Information on the location and credentials for accessing your Real-Time Data Feed can be found in Admin > System Info under "Real-Time Queue".

What this allows you to do is have a series of custom SQL actions which respond immediately to specific campaign events. Individual Activities can be Enabled or Disabled independently of the others, so you can choose to implement any combination of Activities triggering SQL actions.

Activity Types

Activity

Description

Bounce

Message bounced

Spam Complaint

Feedback loop

Unsubscribe

Unsubscribe processing

Click

Click tracking

Open

Open tracking

Delivery

Delivery confirmations

Job Error

Job error

Render Error

Occurs when there is a problem with the template merge process

Managing Event Triggers

Clicking the name of an Activity will open the Event Trigger page where multiple unique SQL actions can be added. Like a Campaign Trigger, the order of the Actions on the page dictates the order in which they are performed.

Pausing and Resuming Event Triggers

When the Real-Time Data Feed triggers are paused, the events continue to queue for up to 14 days. Events start to expire after 14 days. If event processing is Resumed, events queued will initiate the Actions for the resumed Triggers.

Example Use Case: Unsubscribe Event Triggers Opt-Out in Database

A common way to use Real-Time Data Feed event triggers is to maintain a clean database of recipients, and avoid sending further Marketing Emails to anyone who has unsubscribed, bounced, or complained. Here’s an example of an Action on the Unsubscribe event where UnsubActivity changes opt_in to “false” in the connected database:

For another example, here’s a sample of how we have set up an Event Trigger to insert a record of a bounce event into a database:

Note that in both of these examples, the schema and tables referenced are defined by your own team, and not proscribed by the MessageGears platform. In the above update example for UnsubActivity, the behavior is intended to allow existing rows within your database to be updated when an unsubscribe event occurs, allowing for easy integration into your existing system.

This service provides a way to simply and easily consume account activity data in real-time as events (clicks, opens, bounces, etc.) occur. This can be extremely useful for applications using MessageGears that need to capture their activity data more frequently than once a day (i.e. for a job dashboard). The data is formatted using exactly the same XML structure as the AccountActivity API results. The only difference is that the data will come from a queue in many small XML payloads.

Deprecated Versions

v3.1

Implementation

Amazon provides their Simple Queue Service as a way to easily and securely transfer data using their API.

Response Values

Common Response Elements (present for all activity types)

Element Name

Description

ActivityItems

The root element of the XML response.

AccountId

The MessageGears account to which this item belongs

RequestId

The MessageGears request id of the job of which the activity items belongs.

CorrelationId

The correlation id provided with the invocation of this job, if supplied. This field allows you to supply your own job id. This ID is designed to make it easier to match events coming out of MessageGears with the job they belong to in your own system.

ActivityId

The unique activity id for an individual activity item.

Timestamp

The time that the event/activity item occurred.

JobCategory

The job category provided for this job (if supplied). This is a user-defined field and is provided as a convenience. It's purpose is to allow the user to categorize this request and the activity associated with it in internal reporting.

CampaignId

The Campaign Id for this activity (if supplied).

CampaignVersion

The Campaign Version associated with this activity (if associated with a campaign)

EmailAddress

The email address of the recipient responsible for the activity item.

IpAddress

The ip address that generated the activity.

RecipientId

The recipient id provided in the recipient XML (if supplied)

Click the Activity Types below to view more about each activity response, including example responses and complete response elements.

Click Activity Response

<ActivityItems>

<ClickActivity>

<RequestId>t25710-07bc4beb-34de-44d1-85b0-d27628a78b2c</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-14T15:50:19.491-04:00</Timestamp>

<IpAddress>74.60.196.56</IpAddress>

<UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>

<Url>http://www.mycompany.com</Url>

<UrlName>Home Page</UrlName>

<Microsite>true</Microsite>

</ClickActivity>

</ActivityItems>

Element Name

Description

ClickActivity

The element containing all the click information. This is a repeating element, one for each click event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Url

The URL of the clicked link.

UrlName

The name (if any) of the link you provided in the template when the link was made trackable.

Microsite

Will be set to "true" if this event originated from a microsite version of an email message.

Open Activity Response

<ActivityItems>

<OpenActivity>

<RequestId>t25710-07bc4beb-34de-44d1-85b0-d27628a78b2c</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-14T15:49:16.064-04:00</Timestamp>

<IpAddress>74.60.196.56</IpAddress>

<UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>

<Microsite>true</Microsite>

</OpenActivity>

</ActivityItems>

Element Name

Description

OpenActivity

The element containing all the open information. This is a repeating element, one for each open event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Microsite

Will be set to “true” if this event originated from a microsite version of an email message.

Delivery Activity Response

<ActivityItems>

<DeliveredMessageActivity>

<RequestId>t25610-3147e501-c83f-42a5-b638-c476e1237a65</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-13T18:51:00.000-04:00</Timestamp>

<IpAddress>74.125.47.27</IpAddress>

</DeliveredMessageActivity>

</ActivityItems>

Element Name

Description

DeliveredMessageActivity

The element containing all the delivery information. This is a repeating element, one for each email delivered for the specified day.

Bounce Activity Response

<ActivityItems>

<BouncedMessageActivity>

<RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-13T19:10:54.000-04:00</Timestamp>

<Category>Invalid Recipient</Category>

<CategoryCode>10</CategoryCode>

<Details>550-5.1.1 The email account that you tried to reach does not exist.</Details>

<IpAddress>74.125.47.27</IpAddress>

</BouncedMessageActivity>

</ActivityItems>

Element Name

Description

BouncedMessageActivity

The element containing all the bounce information. This is a repeating element, one for each bounce event for the specified day.

Category

A general category of the bounce.

CategoryCode

A unique code that identifies the category of the bounce.

Details

The detailed bounce message.

Bounce Categories

Please remove all bounces of type 10 and 30. Failure to do so may negatively impact your inbox performance with the various ISPs.

Category

Category Code

Description

Undetermined

1

The response text could not be identified.

Invalid Recipient

10

The recipient is invalid.

Soft Bounce

20

The message soft bounced.

DNS Failure

21

The message bounced due to a DNS failure.

Mailbox Full

22

The message bounced due to the remote mailbox being over quota.

Too Large

23

The message bounced because it was too large for the recipient.

Timeout

24

The message timed out.

Admin Failure

25

The message was failed by configured policies.

Generic Bounce: No RCPT

30

No recipient could be determined for the message.

Generic Bounce

40

The message failed for unspecified reasons.

Mail Block

50

The message was blocked by the receiver.

Spam Block

51

The message was blocked by the receiver as coming from a known spam source.

Spam Content

52

The message was blocked by the receiver as spam.

Prohibited Attachment

53

The message was blocked by the receiver because it contained an attachment.

Relay Denied

54

The message was blocked by the receiver because relaying is not allowed.

Transient Failure

70

Message transmission has been temporarily delayed.

Invalid Email Syntax

110

The message has a malformed/invalid email address.

Hardbounce Suppression

130

The message is a known-bad email address and has hard-bounces with a category 10 or 30 in the past. It was suppressed from sending to protect IP reputation with the ISP.

Unsubscribe Suppression

131

The recipient of the message has unsubscribed from a message from your account in the past. It was suppressed from sending to protect your sending reputation.

Fbl Suppression

132

The recipient of the message has filed a spam complaint with your account in the past. It was suppressed from sending to protect your sending reputation.

Complainer Suppression

133

The recipient of the message is a known complainer. It was suppressed from sending to protect your sending reputation.

Domain Suppression

134

The recipient domain is not allowed. It was suppressed from sending to protect your sending reputation.

Role Suppression

135

The recipient address is not allowed. It was suppressed from sending to protect your sending reputation.

Unsubscribe Activity Response

<ActivityItems>

<UnsubActivity>

<RequestId>t25810-eec987c5-085b-4d40-a4ce-24a5850638a5</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-15T16:14:46.878-04:00</Timestamp>

<IpAddress>128.234.11.12</IpAddress>

<UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>

</UnsubActivity>

</ActivityItems>

Element Name

Description

UnsubActivity

The element containing all the unsub information. This is a repeating element, one for each open event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Microsite

Will be set to “true” if this event originated from a microsite version of an email message.

Spam Complaint Activity Response

<ActivityItems>

<SpamComplaintActivity>

<RequestId>t25810-eec987c5-085b-4d40-a4ce-24a5850638a5</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-15T16:14:46.878-04:00</Timestamp>

<Isp>gmail.com</Isp>

</SpamComplaintActivity>

</ActivityItems>

Element Name

Description

SpamComplaintActivity

The element containing the Spam Complaint information. This is a repeating element, one for each complaint received for the specified day.

Isp

The domain part of the recipient’s email address.

Job Error Activity Response

<ActivityItems>

<JobErrorActivity>

<RequestId>t25710-9540c8d8-aa5d-44d7-a9ef-a334072df515</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<Timestamp>2010-09-14T13:20:36.994-04:00</Timestamp>

<JobError>

<ErrorCode>Transfer Error</ErrorCode>

<ErrorMessage>AmazonClientException retrieving file: s3://mycompany/myfile.txt - The specified key does not exist.</ErrorMessage>

</JobError>

</JobErrorActivity>

</ActivityItems>

Element Name

Description

JobErrorActivity

The element containing theJob Error information. This is a repeating element, one for each job that failed to be processed for the specified day.

JobError

A repeating element, one for each error that occurred.

ErrorCode

A general error code for the failure.

ErrorMessage

A detailed error description.

Render Error Activity Response

<ActivityItems>

<RenderErrorActivity>

<RequestId>t25610-0b74f4c6-fe21-411f-bba9-82818bf1c31b</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-13T19:13:46.220-04:00</Timestamp>

<RenderErrors>

<RenderError>

<ErrorCode>Template merge exception</ErrorCode>

<ErrorMessage>Error on line 1, column 10 in SUBJECT Expecting a string, date or number here, Expression Recipient.FirstNamex is instead a freemarker.ext.dom.NodeListModel</ErrorMessage>

</RenderError>

</RenderErrors>

</RenderErrorActivity>

</ActivityItems>

Element Name

Description

RenderErrorActivity

The element containing the error information regarding the rendering of an email message. This is a repeating element, one for each email that failed to be rendered for the specified day.

Erro Code

A general error code for the failure.

ErrorMessage

A detailed error description.

Programming Examples

Java SDK

C# SDK

Java SDK

package com.messagegears.sdk.examples;

import com.messagegears.sdk.v3_1.BouncedMessageActivity;

import com.messagegears.sdk.v3_1.ClickActivity;

import com.messagegears.sdk.v3_1.DeliveredMessageActivity;

import com.messagegears.sdk.v3_1.JobErrorActivity;

import com.messagegears.sdk.v3_1.OpenActivity;

import com.messagegears.sdk.v3_1.RenderErrorActivity;

import com.messagegears.sdk.v3_1.SpamComplaintActivity;

import com.messagegears.sdk.v3_1.UnsubActivity;

import com.messagegears.sdk.MessageGearsListener;

import com.messagegears.sdk.aws.MessageGearsAwsProperties;

import com.messagegears.sdk.aws.MessageGearsAwsQueuePoller;

import com.messagegears.sdk.output.ScreenWriter;

public class ActivityFeedExample implements MessageGearsListener {

public static final String MY_AWS_ACCOUNT_ID = "place your aws account id here";

public static final String MY_AWS_SECRET_KEY = "place your aws secret key here";

public static final String MY_AWS_QUEUE = "place your sqs queue url here";

public static void main (String[] args) {

// Create the AWS properties object

MessageGearsAwsProperties props = new MessageGearsAwsProperties();

props.setMyAwsAccountKey(MY_AWS_ACCOUNT_ID);

props.setMyAwsSecretKey(MY_AWS_SECRET_KEY);

props.setMyAwsEventQueueUrl(MY_AWS_QUEUE);

// Create an object of this listener class and start the poller passing in the listener

ActivityFeedExample listener = new ActivityFeedExample();

MessageGearsAwsQueuePoller poller = new MessageGearsAwsQueuePoller(props, listener);

poller.start();

}

public void onOpen(OpenActivity activity) {

ScreenWriter.print(activity);

}

public void onClick(ClickActivity activity) {

ScreenWriter.print(activity);

}

public void onBounce(BouncedMessageActivity activity) {

ScreenWriter.print(activity);

}

public void onDelivery(DeliveredMessageActivity activity) {

ScreenWriter.print(activity);

}

public void onSpamComplaint(SpamComplaintActivity activity) {

ScreenWriter.print(activity);

}

public void onJobError(JobErrorActivity activity) {

ScreenWriter.print(activity);

}

public void onRenderError(RenderErrorActivity activity) {

ScreenWriter.print(activity);

}

public void onUnsub(UnsubActivity activity) {

ScreenWriter.print(activity);

}

}

C# SDK

using System;

using MessageGears.Model.Generated;

using MessageGears.EventQueue;

namespace MessageGears.Examples

{

public class ActivityFeedExample : MessageGearsListener

{

public const String MY_AWS_ACCOUNT_ID = "place your aws account id here";

public const String MY_AWS_SECRET_KEY = "place your aws secret key here";

public const String MY_AWS_QUEUE = "place your sqs queue url here";

public static void Main ()

{

// Create the AWS properties object

MessageGearsAwsProperties props = new MessageGearsAwsProperties();

props.MyAWSAccountKey = MY_AWS_ACCOUNT_ID;

props.MyAWSSecretKey = MY_AWS_SECRET_KEY;

props.MyAWSEventQueueUrl = MY_AWS_QUEUE;

// Create an object of this listener class and start the poller passing in the listener

ActivityFeedExample listener = new ActivityFeedExample();

MessageGearsAwsQueuePoller poller = new MessageGearsAwsQueuePoller(props, listener);

poller.Start();

}

public void OnOpen(OpenActivity activity)

{

Console.WriteLine("***** Open Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine("UserAgent: " + activity.UserAgent);

Console.WriteLine();

}

public void OnClick(ClickActivity activity)

{

Console.WriteLine("***** Click Event Received: " + activity.ActivityId);

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine("Url: " + activity.Url);

Console.WriteLine("UrlName: " + activity.UrlName);

Console.WriteLine("UserAgent: " + activity.UserAgent);

Console.WriteLine();

}

public void OnBounce(BouncedMessageActivity activity)

{

Console.WriteLine("***** Bounce Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("Category: " + activity.Category);

Console.WriteLine("CategoryCode: " + activity.CategoryCode);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("Details: " + activity.Details);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("MessageSize: " + activity.MessageSize);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine();

}

public void OnDelivery(DeliveredMessageActivity activity)

{

Console.WriteLine("***** Delivery Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("MessageSize: " + activity.MessageSize);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine();

}

public void OnSpamComplaint(SpamComplaintActivity activity)

{

Console.WriteLine("***** Spam Complaint Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("Isp: " + activity.Isp);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Subject: " + activity.Subject);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine();

}

public void OnJobError(JobErrorActivity activity)

{

Console.WriteLine("***** Job Error Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("JobError: " + activity.JobError);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine();

}

public void OnRenderError(RenderErrorActivity activity)

{

Console.WriteLine("***** Render Error Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RenderErrors: " + activity.RenderErrors);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine();

}

public void OnUnsub(UnsubActivity activity)

{

Console.WriteLine("***** Unsub Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine("UserAgent: " + activity.UserAgent);

Console.WriteLine();

}

}

}

AccountActivity is used to retrieve a file containing all of the activity data for a single day for an activity type. If you need to retrieve your data more frequently that once a day, you should considering using the “Event Feed” which will allow you to consume the same activity/events as they occur. This API differs from others in that it “streams” back a large binary byte array. It can be invoked via using utilities like WGET or CURL, or you can write your code to retrieve the data. It’s important to remember that these files can be large and often will be too large to fit into memory all at once. Write your code so that the file is streamed to disk or to a database for processing.

XSD Location

For a detailed list of all response values, refer to the XSD file below.

https://api.messagegears.net/3.1/WebService?Action=XSD

Deprecated Versions

v3.0 (unchanged in 3.1)

Input Parameters

Parameter

Description

Action

AccountActivity

AccountId

The MessageGears account id to which this item belongs.

ApiKey

A secret key only known by you. Keep this key confidential.

ActivityDate

The date of the activity that is being requested. This field must be in the form of yyyy-MM-dd (example: 2010-12-31).

ActivityType

One of the following strings must be provided: BOUNCES, CLICKS, OPENS, DELIVERIES, SPAM_COMPLAINTS, UNSUBSCRIBES, RENDER_ERRORS, JOB_ERRORS.

UseCompression

Set whether the data returned is compressed in .zip format. Set to TRUE to download the data in a compressed format (this is the suggested method)

Response Values

Common Response Elements (present for all activity types)

Element Name

Description

ActivityItems

The root element of the XML response.

RequestId

The MessageGears request id of the job of which the activity items belongs.

CorrelationId

The correlation id provided with the invocation of this job, if supplied. This field allows you to supply your own job id. This ID is designed to make it easier to match events coming out of MessageGears with the job they belong to in your own system.

ActivityId

The unique activity id for an individual activity item.

Timestamp

The time that the event/activity item occurred.

EmailAddress

The email address of the recipient responsible for the activity item.

IpAddress

The ip address that generated the activity.

Click the Activity Types below to view more about each activity response, including example responses and complete response elements.

Click Activity Response

<ActivityItems>

<ClickActivity>

<RequestId>t25710-07bc4beb-34de-44d1-85b0-d27628a78b2c</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-14T15:50:19.491-04:00</Timestamp>

<IpAddress>74.60.196.56</IpAddress>

<UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>

<Url>http://www.mycompany.com</Url>

<UrlName>Home Page</UrlName>

<Microsite>true</Microsite>

</ClickActivity>

</ActivityItems>

Element Name

Description

ClickActivity

The element containing all the click information. This is a repeating element, one for each click event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Url

The URL of the clicked link.

UrlName

The name (if any) of the link you provided in the template when the link was made trackable.

Microsite

Will be set to "true" if this event originated from a microsite version of an email message.

Open Activity Response

<ActivityItems>

<OpenActivity>

<RequestId>t25710-07bc4beb-34de-44d1-85b0-d27628a78b2c</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-14T15:49:16.064-04:00</Timestamp>

<IpAddress>74.60.196.56</IpAddress>

<UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>

<Microsite>true</Microsite>

</OpenActivity>

</ActivityItems>

Element Name

Description

OpenActivity

The element containing all the open information. This is a repeating element, one for each open event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Microsite

Will be set to “true” if this event originated from a microsite version of an email message.

Delivery Activity Response

<ActivityItems>

<DeliveredMessageActivity>

<RequestId>t25610-3147e501-c83f-42a5-b638-c476e1237a65</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-13T18:51:00.000-04:00</Timestamp>

<IpAddress>74.125.47.27</IpAddress>

</DeliveredMessageActivity>

</ActivityItems>

Element Name

Description

DeliveredMessageActivity

The element containing all the delivery information. This is a repeating element, one for each email delivered for the specified day.

Bounce Activity Response

<ActivityItems>

<BouncedMessageActivity>

<RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-13T19:10:54.000-04:00</Timestamp>

<Category>Invalid Recipient</Category>

<CategoryCode>10</CategoryCode>

<Details>550-5.1.1 The email account that you tried to reach does not exist.</Details>

<IpAddress>74.125.47.27</IpAddress>

</BouncedMessageActivity>

</ActivityItems>

Element Name

Description

BouncedMessageActivity

The element containing all the bounce information. This is a repeating element, one for each bounce event for the specified day.

Category

A general category of the bounce.

CategoryCode

A unique code that identifies the category of the bounce.

Details

The detailed bounce message.

Bounce Categories

Please remove all bounces of type 10 and 30. Failure to do so may negatively impact your inbox performance with the various ISPs.

Category

Category Code

Description

Undetermined

1

The response text could not be identified.

Invalid Recipient

10

The recipient is invalid.

Soft Bounce

20

The message soft bounced.

DNS Failure

21

The message bounced due to a DNS failure.

Mailbox Full

22

The message bounced due to the remote mailbox being over quota.

Too Large

23

The message bounced because it was too large for the recipient.

Timeout

24

The message timed out.

Admin Failure

25

The message was failed by configured policies.

Generic Bounce: No RCPT

30

No recipient could be determined for the message.

Generic Bounce

40

The message failed for unspecified reasons.

Mail Block

50

The message was blocked by the receiver.

Spam Block

51

The message was blocked by the receiver as coming from a known spam source.

Spam Content

52

The message was blocked by the receiver as spam.

Prohibited Attachment

53

The message was blocked by the receiver because it contained an attachment.

Relay Denied

54

The message was blocked by the receiver because relaying is not allowed.

Transient Failure

70

Message transmission has been temporarily delayed.

Invalid Email Syntax

110

The message has a malformed/invalid email address.

Hardbounce Suppression

130

The message is a known-bad email address and has hard-bounces with a category 10 or 30 in the past. It was suppressed from sending to protect IP reputation with the ISP.

Unsubscribe Suppression

131

The recipient of the message has unsubscribed from a message from your account in the past. It was suppressed from sending to protect your sending reputation.

Fbl Suppression

132

The recipient of the message has filed a spam complaint with your account in the past. It was suppressed from sending to protect your sending reputation.

Complainer Suppression

133

The recipient of the message is a known complainer. It was suppressed from sending to protect your sending reputation.

Domain Suppression

134

The recipient domain is not allowed. It was suppressed from sending to protect your sending reputation.

Role Suppression

135

The recipient address is not allowed. It was suppressed from sending to protect your sending reputation.

Unsubscribe Activity Response

<ActivityItems>

<UnsubActivity>

<RequestId>t25810-eec987c5-085b-4d40-a4ce-24a5850638a5</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-15T16:14:46.878-04:00</Timestamp>

<IpAddress>128.234.11.12</IpAddress>

<UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>

</UnsubActivity>

</ActivityItems>

Element Name

Description

UnsubActivity

The element containing all the unsub information. This is a repeating element, one for each open event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Microsite

Will be set to “true” if this event originated from a microsite version of an email message.

Spam Complaint Activity Response

<ActivityItems>

<SpamComplaintActivity>

<RequestId>t25810-eec987c5-085b-4d40-a4ce-24a5850638a5</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-15T16:14:46.878-04:00</Timestamp>

<Isp>gmail.com</Isp>

</SpamComplaintActivity>

</ActivityItems>

Element Name

Description

SpamComplaintActivity

The element containing the Spam Complaint information. This is a repeating element, one for each complaint received for the specified day.

Isp

The domain part of the recipient’s email address.

Job Error Activity Response

<ActivityItems>

<JobErrorActivity>

<RequestId>t25710-9540c8d8-aa5d-44d7-a9ef-a334072df515</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<Timestamp>2010-09-14T13:20:36.994-04:00</Timestamp>

<JobError>

<ErrorCode>Transfer Error</ErrorCode>

<ErrorMessage>AmazonClientException retrieving file: s3://mycompany/myfile.txt - The specified key does not exist.</ErrorMessage>

</JobError>

</JobErrorActivity>

</ActivityItems>

Element Name

Description

JobErrorActivity

The element containing theJob Error information. This is a repeating element, one for each job that failed to be processed for the specified day.

JobError

A repeating element, one for each error that occurred.

ErrorCode

A general error code for the failure.

ErrorMessage

A detailed error description.

Render Error Activity Response

<ActivityItems>

<RenderErrorActivity>

<RequestId>t25610-0b74f4c6-fe21-411f-bba9-82818bf1c31b</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-13T19:13:46.220-04:00</Timestamp>

<RenderErrors>

<RenderError>

<ErrorCode>Template merge exception</ErrorCode>

<ErrorMessage>Error on line 1, column 10 in SUBJECT Expecting a string, date or number here, Expression Recipient.FirstNamex is instead a freemarker.ext.dom.NodeListModel</ErrorMessage>

</RenderError>

</RenderErrors>

</RenderErrorActivity>

</ActivityItems>

Element Name

Description

RenderErrorActivity

The element containing the error information regarding the rendering of an email message. This is a repeating element, one for each email that failed to be rendered for the specified day.

Erro Code

A general error code for the failure.

ErrorMessage

A detailed error description.

Programming Examples

REST

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=AccountActivity

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&ActivityDate=2010-12-31

&ActivityType=BOUNCES

See above for examples of each response by ActivityType

Java SDK

Click here for more information on using the MessageGears Java SDK

package com.messagegears.sdk.examples;

import java.io.File;

import java.io.FileInputStream;

import java.io.FileNotFoundException;

import java.util.Calendar;

import java.util.Date;

import com.messagegears.sdk.v3_1.BouncedMessageActivity;

import com.messagegears.sdk.v3_1.ClickActivity;

import com.messagegears.sdk.v3_1.DeliveredMessageActivity;

import com.messagegears.sdk.v3_1.JobErrorActivity;

import com.messagegears.sdk.v3_1.OpenActivity;

import com.messagegears.sdk.v3_1.RenderErrorActivity;

import com.messagegears.sdk.v3_1.SpamComplaintActivity;

import com.messagegears.sdk.v3_1.UnsubActivity;

import com.messagegears.sdk.MessageGearsClient;

import com.messagegears.sdk.MessageGearsListener;

import com.messagegears.sdk.MessageGearsProperties;

import com.messagegears.sdk.activity.MessageGearsActivityFileProcessor;

import com.messagegears.sdk.model.ActivityType;

import com.messagegears.sdk.model.request.AccountActivityRequest;

import com.messagegears.sdk.output.ScreenWriter;

public class ActivityFileExample implements MessageGearsListener {

public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "your MessageGears Account Id";

public static final String MY_MESSAGEGEARS_API_KEY = "your MessageGears API Key";

public static Date activityDate;

public static void main (String[] args)

{

// Create the AWS properties object

MessageGearsProperties props = new MessageGearsProperties();

props.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);

props.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

// Create the main client object

MessageGearsClient client = new MessageGearsClient(props);

// Create an object of this listener class and process

ActivityFileExample listener = new ActivityFileExample();

// Create a file processor object, and request processing

MessageGearsActivityFileProcessor processor = new MessageGearsActivityFileProcessor(listener);

// Set date to yesterday.

Calendar calendar = Calendar.getInstance();

calendar.add(Calendar.DAY_OF_YEAR, -1);

activityDate = calendar.getTime();

AccountActivityRequest request = new AccountActivityRequest();

request.setDate(activityDate);

// Download the activity files and process them.

for (ActivityType activityType : ActivityType.values()) {

try {

request.setActivityType(activityType);

String downloadedFileName = client.accountActivity(request);

FileInputStream inputStream = new FileInputStream(new File(downloadedFileName));

processor.process(inputStream, activityType);

} catch (FileNotFoundException fnfe) {

System.err.println("Error processing activity of type: " + activityType.name());

System.err.println("FileNotFoundException: " + fnfe.getMessage());

}

}

}

public void onOpen(OpenActivity activity) {

ScreenWriter.print(activity);

}

public void onClick(ClickActivity activity) {

ScreenWriter.print(activity);

}

public void onBounce(BouncedMessageActivity activity) {

ScreenWriter.print(activity);

}

public void onDelivery(DeliveredMessageActivity activity) {

ScreenWriter.print(activity);

}

public void onSpamComplaint(SpamComplaintActivity activity) {

ScreenWriter.print(activity);

}

public void onJobError(JobErrorActivity activity) {

ScreenWriter.print(activity);

}

public void onRenderError(RenderErrorActivity activity) {

ScreenWriter.print(activity);

}

public void onUnsub(UnsubActivity activity) {

ScreenWriter.print(activity);

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;

using MessageGears;

using MessageGears.Model;

using MessageGears.Model.Generated;

namespace MessageGears.Examples

{

public class ActivityFileExample : MessageGearsListener

{

public const String MY_MESSAGEGEARS_ACCOUNT_ID = "your MessageGears Account Id";

public const String MY_MESSAGEGEARS_API_KEY = "your MessageGears API Key";

public static DateTime activityDate = System.DateTime.Today.AddDays(-1);

public static void Main ()

{

// Create the AWS properties object

MessageGearsProperties props = new MessageGearsProperties();

props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;

props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

// Create the main client object

MessageGearsClient client = new MessageGearsClient(props);

// Create an object of this listener class and process

ActivityFileExample listener = new ActivityFileExample();

// Create a file processor object, and request processing

MessageGearsActivityFileProcessor processor = new MessageGearsActivityFileProcessor(listener);

// Download the activity files and process them.

processor.process(client.AccountActivity(activityDate, ActivityType.BOUNCES));

processor.process(client.AccountActivity(activityDate, ActivityType.CLICKS));

processor.process(client.AccountActivity(activityDate, ActivityType.DELIVERIES));

processor.process(client.AccountActivity(activityDate, ActivityType.JOB_ERRORS));

processor.process(client.AccountActivity(activityDate, ActivityType.OPENS));

processor.process(client.AccountActivity(activityDate, ActivityType.RENDER_ERRORS));

processor.process(client.AccountActivity(activityDate, ActivityType.SPAM_COMPLAINTS));

processor.process(client.AccountActivity(activityDate, ActivityType.UNSUBSCRIBES));

}

public void OnOpen(OpenActivity activity)

{

Console.WriteLine("***** Open Event Received");

}

public void OnClick(ClickActivity activity)

{

Console.WriteLine("***** Click Event Received: " + activity.ActivityId);

}

public void OnBounce(BouncedMessageActivity activity)

{

Console.WriteLine("***** Bounce Event Received");

}

public void OnDelivery(DeliveredMessageActivity activity)

{

Console.WriteLine("***** Delivery Event Received");

}

public void OnSpamComplaint(SpamComplaintActivity activity)

{

Console.WriteLine("***** Spam Complaint Event Received");

}

public void OnJobError(JobErrorActivity activity)

{

Console.WriteLine("***** Job Error Event Received");

}

public void OnRenderError(RenderErrorActivity activity)

{

Console.WriteLine("***** Render Error Event Received");

}

public void OnUnsub(UnsubActivity activity)

{

Console.WriteLine("***** Unsub Event Received");

}

}

}

The MessageGears Web Services are RESTful in style. Making an API call is as simple as submitting a URL with specific name/value pairs. Once a request has been submitted, the service will respond with an XML document. The results will conform to an XML Schema Definition (XSD) which can be used to auto-generate source code. For more information, please see our API overview here

XSD Location

https://api.messagegears.net/3.1/WebService?Action=XSD

Base URL

https://api.messagegears.net/3.1/WebService

Web Services

You should always use the HTTP POST method when calling the APIs from your application. For demonstration purposes, the examples shown for each API call use the HTTP GET method which has a very small size limit (approx. 2KB). The POST methods for our services will accept requests of up to 2MB.

Web Service

Description

TransactionalJobSubmit

Send individual, personalized email messages. This API sends a single email per invocation.

BulkJobSubmit

Send email messages to a list of recipients. There is no hard limit on the size of the list and millions of emails can be sent from a single invocation of this API.

BulkJobSummary

Check the status of a bulk job. It returns the total deliveries, clicks, opens, bounces, unsubscribes, and spam complaints.

AccountActivity

Retrieve your detailed account activity for a given day (deliveries, clicks, opens, bounces, etc.)

AccountSummary

Retrieve summary information for your account for a given day (deliveries, clicks, opens, bounces, etc.)

RealTimeAccountActivity

Retrieve all your detailed account activity in "real time" (deliveries, clicks, opens, bounces, etc.) using Amazon Simple Queue Service (SQS).

MessagePreview

Test the rendering of an email template. Many parts of each email message sent using the Bulk and Transactional APIs can be personalized using a template language. This API is very useful for those who are building email marketing tools and need a way to allow content authors to test dynamic email content as they develop it.

TransactionalCampaignSubmit

Send individual, personalized email messages using a template stored in our content manager.

BulkCampaignSubmit

Send email messages to a list of email addresses using a template stored in our content manager.

CreateAccount

Creates a new child account.

UpdateAccount

Updates a new child account.

Thumbnail

Creates a Thumbnail Image (.jpg) from html or text content. The image is intended to be used to create a thumbnail representation of a Template.

TransactionalContentRetrieval

Used to render a delivered transactional job or campaign.

ForwardToAFriend

Used to send a single email to a single email address, including a copy of a message previously sent through the MessageGears platform. (REST only)

Common Response Values (returned by all APIs)

Parameter

Data Type

Description

RequestId

String

The unique id for this API call.

Result

String

Result will always be REQUEST_SUCCESSFUL or REQUEST_FAILED. If REQUEST_FAILED is returned, you will also receive a list of one or more errors which occurred in attempting to process the API request.

Example Success Response

<TransactionalJobSubmitResponse>

<RequestId>t23110-a9e77b7c-c980-4ff5-8ede-546fbe0bad66</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

</TransactionalJobSubmitResponse>

Example Failure Response

<TransactionalJobSubmitResponse>

<RequestId>t13912-991142c3-00de-48ca-9ba9-7881631248e7</RequestId>

<Result>REQUEST_FAILED</Result>

<RequestErrors>

<RequestError>

<ErrorCode>AuthenticationException</ErrorCode>

<ErrorMessage>The accountId and/or password are invalid.</ErrorMessage>

</RequestError>

</RequestErrors>

</TransactionalJobSubmitResponse>

In the Content section of Accelerator, users can create and manage Templates and Shared Content.

A template is constructed of the HTML, text, and header content used to design the email message which will later be sent out from a Campaign.

Before any emails can be sent out through MessageGears Accelerator, Templates must first be created containing the desired content. Templates give you the freedom to reuse the same design in future campaigns, while populating in personalized campaign content using FreeMarker, Snippets, and Shared Content.

In this articlewe’re going to walk through creating a Template in MessageGears Accelerator.

Table of Contents

Template Overview

Template Settings

Sample Recipient Data

Upload Recipient File for Sample Recipient Data

Context Data

Headers

HTML

HTML Source Editor

WYSIWYG Editor

Import File

Considerations

Text

Snippets

Add a Snippet

Testing

Personalization (Testing & Preview)

Spam Filter Testing

Content Evaluation

Email Clients

Subject Line

Personalization Fields (Reference)

Personalizable Fields

MessageGears Functions

FreeMarker Directives

To add a new Template, on the Content > Template page select the blue Actions button and "Add Template". This will open a page where you can name and add a description to your template. https://support.messagegears.com/hc/en-us/articles/115000851927-FreeMarker-Template-Language

You are then brought to an overview page with a menu of options on the left side of the screen. This guide is going to go through these pages step-by-step.

Template Overview

The Overview page provides a preview of the template’s design as well as important details about the template’s size, spam score, and most recent update.

This table can be used as a quick reference for the descriptions and uses of each page. It can also be referred to via the Help option on the Overview page of the Template:

Click

to go to

where you can

Settings

Settings page

view or change the template name and description.

Sample Recipient Data

Sample Recipient Data page

view or edit sample data in list or source code format used to personalize the message

Context Data

Context Test Data page

view or edit context data in a table or source format used to personalize the message

Headers

Headers page

add, view, or edit sending profile data, including email header and subject info

HTML

HTML Content page

import, view, or edit HTML content in a WYSIWYG or source editor view.

Text

Text Content page

create the text version of your template manually or generate text automatically from HTML.

Snippets

Local Snippets library for the current Template

HTML or FreeMarker snippets used to render this template

Personalization

Personalization Test Results page

test personalization and rendering time results across HTML and text content versions.

Spam Filter

Spam Filter Test Results page

view resulting spam score associated with the template.

Content Evaluation

Content Evaluation Tests page

view likelihood of email to reach the intended recipient across popular spam filters.

Email Clients

Email Clients Tests page

view how content renders across various email clients, including mobile platforms.

Subject Line

Desktop Email Clients section

view how subject lines render across popular email clients.

Personalization Fields

Dynamic Template Help pop-up window

view the available fields, functions and FreeMarker options that you can copy and paste into your template source code.

Template Settings

On the Settings page, you can update the Name and Description of the template.

Sample Recipient Data

Sample Recipient Data consists of representative personalization fields related to a recipient list, and it is used to validate personalization accuracy. When Sample Recipient Data is pulled into a campaign, that data will be present in the previews and tests of the campaign to serve as an example of how personalization will display for that particular set of data.

Use the "Refresh sample" dropdown to select a pre-existing Recipient Data source, or select the "Upload Recipient File" option to import a CSV or XML file as the Sample Recipient Data.

In order to provide pre-existing options in the sample drop down, there will need to be Database Queries and/or URL Data Sources in the Audience section of Accelerator created with a Data Type of "Recipient":

Upload Recipient File for Sample Recipient Data

When uploading a new Recipient File, there are a few different options and different requirements for each:

XML file requirements:

ends with .xml,

has a root element of "RecipientList"

each "Recipient" element has an "EmailAddress" node

CSV or TSV file requirements:

required EmailAddress header

all other field names must contain only alphanumeric (A-Z 0-9) values with no special characters

ends with .csv or .tsv

file has properly named headers:

all file rows contain the same number of elements

Compressed file

ZIP (ending in .zip)

GZIP (ending in .gz or .gzip)

ZLIB (files ending in .zlib or .dzip)

full name should end with the original file type extension, and then the compression extension (i.e. a zip file containing an xml file named sample-recipients would be sample-recipients.xml.zip)

Beneficial if you have a large number of sample recipients.

Currently supported compression schemas:

Requirements:

Context Data

Context Data is an optional XML source that contains data shared across all recipients for the job being processed. This data may be used to provide offer/deal content that is available for all recipients, such as "Today's Hot Travel Deals". This deal information may be presented to all recipients of the mailing, or logic within the template can be used to match the best deal/offer for each individual recipient, generated a true one-to-one message.

Context Data XML can be provided in any well-formed XML structure, and elements are referenced in the template based on the format provided.

Use the “Refresh sample from datasource” dropdown to select a pre-existing Context Data source, or data can be created manually by selecting the "Source" tab.

In order to provide options in the datasource drop down, there will need to be Database Queries and/or URL Data Sources in the Audience section of Accelerator created with a Data Type of "Context":

Headers

The Headers page provides a view of any existing Header settings. By clicking "Edit Headers" these can be updated to the desired From Name, From Address, Reply To Address, and Subject Line for this Template.

From Name indicates what the recipient will see in the From field of their email inbox.

From Address will be the email address the email appears to have been sent from, and this address usually corresponds directly to the From Name.

Reply To Address is often set to be the same address as From Address, but it can be set as a different address. The purpose of the Reply To Address is to indicate what email address will populate to To field when a recipient hits Reply to the email in their inbox.

Subject Line indicates what should be visible in the Subject of this email.

When adding or editing Header information, it is possible to select a pre-populated set of data if you have Sending Profiles set up in your account under Admin > Sending Profiles. To populate an existing Sending Profile, start typing the name into the Sending Profile box and it will pop up below as an option.

Note: Sending Profiles *only* populate From Name, From Address, and Reply To Address. Subject Line still needs to be provided.

HTML

There are three modes of adding content to the template.

HTML Source Editor

Using the HTML Source Editor, you can paste in HTML code to create the content of the email. All of the CSS, HTML, and FreeMarker personalization content will be visible in this mode.

WYSIWYG (What You See Is What You Get) Editor

The WYSIWYG Editor allows editors who aren’t necessarily code-savvy to generate attractive, simple email content. The abilities of the WYSIWYG Editor in Accelerator are similar to the features found in text editing software such as font styling and adding tables.

Import File

Pre-existing HTML files can be imported directly to MessageGears Accelerator for use as a template. We recommend thorough testing of imported content to make sure it displays as expected in inboxes.

Considerations

We discourage switching between the HTML and WYSIWYG editors - for the best results, stick with one mode of editing. Personalization can be added in either mode.

To add personalization, click Personalization Fields in the left pane to open the popup, then click to copy the desired field(s) and paste it directly into the source.

Another thing to keep in mind is that MessageGears doesn’t host images or asset files for use in template content. When coding or importing, it is important that any assets included in the HTML are provided with absolute URL paths which can render in external recipient inboxes as well as internal previews and tests.

Text

The Text Content page allows for the manual or automatic creation of a plain-text version of the template.

"Create Manually" gives the creator the freedom to write custom plain-text content, while "Generate from HTML" isolates any regular text content from the HTML into a plain-text version.

Once the original selection is made, users can "Edit Text" to manually change elements of the plain-text content. Selecting "Generate from HTML" will overwrite the existing plain-text with the most recent version of the text from the HTML content. Any changes made manually to the plain-text will be lost.

Snippets

Snippets are macros, functions, HTML, or other coded content for use within a single template. Once a Snippet has been created and saved, it can be pulled into the template using FreeMarker code.

The code for including Snippets in a template looks like this:

<#include '/local/yoursnippetname'>

Add a Snippet

When adding a Snippet, you are brought to the Add Shared Content page. Once a name is added, and a description if desired, you’ll be brought to the Content Snippet editor. Here you can toggle between the HTML and WYSIWYG editors, import a file, and test the snippet. Once a snippet is created, you’ll navigate back to the local (template-specific) snippets folder, and ultimately back to the template’s Overview page.

Since a Snippet is local to this template, it won’t be accessible by other templates. If you'd like to create Shared Content for multiple templates to use, refer to the article about Adding Shared Content.

Testing

Personalization (Testing & Preview)

On the Personalization page, you can generate a live test of the content on the page in order to test personalization rendering times and results across HTML and text content versions. Personalization relies on the Sample Recipient Data provided earlier in the process to display a preview of how the provided recipient data and personalized will render together.

Spam Filter Testing

On the Spam Filter page, you can generate and view spam scores associated with the template. This can help to identify content issues which may lead to the campaign emails landing in spam folders rather than recipients’ inboxes.

This tool is powered by SpamAssassin, a commonly used spam filter.

Content Evaluation

Running a Content Evaluation Test provides insight into how the template and content interacts with over 14 commonly used spam filters and checkpoints for email deliverability. Content Evaluation provides deeper insight into deliverability concerns than the Spam Filter test, and checks against DKIM, SPF, and other elements of email authentication.

This tool is powered by Litmus, a platform for testing email templates, content, and deliverability.

Multiple evaluations can be run, and all tests can be accessed in a list on the Content Evaluation page. A test can be left to complete and revisited later to view full results.

Email Clients

Running an Email Clients Test is similar to a Content Evaluation, but rather than evaluating the template against spam filters and authentication checkpoints, Email Clients testing will illuminate how the template will display in over 30 different email clients and on different devices. This testing tool is also powered by Litmus.

Multiple tests can be run, and all tests can be accessed in a list on the Email Clients page. A test can be left to complete and revisited later to view full results. Once a test starts to populate thumbnails, each thumbnail can be clicked to view a larger screenshot displaying the template rendered in a particular email client.

Tip: If you know your recipient list is largely Outlook users, for example, paying close attention to the Outlook screenshots is recommended. It’s useful to focus efforts on the email clients you know are most heavily used by your recipients.

Subject Line

The Subject Line tester allows you to view how the From Name and Subject Line will display in a variety of different email inboxes.

Personalization Fields (Reference)

The bottom-most selection of the Template menu is Personalization Fields, and this item brings up a Dynamic Template Help pop-up window containing a list of click-to-copy FreeMarker and MessageGears functions to add to your content for personalization.

Clicking on an item copies the code into your clipboard, which can then be pasted into the HTML or text body of your template.

Personalizable Fields

These Personalizable Fields are frequently-used Recipient or Job related FreeMarker variables which can be used to personalize content - including links - in the template.

Personalizable Field

Code

EmailAddress

${Recipient.EmailAddress}

Current Date

${Gears.date?date}

Request Id

${Gears.requestId}

Correlation Id

${Gears.correlationId}

Job Category

${Gears.jobCategory}

MessageGears Functions

MessageGears Functions contains a set of frequently-used commands used to personalize messages with MessageGears-specific items such as a “view in browser” microsite link or an unsubscribe link. Clicking on an item copies the code into your clipboard, which can then be pasted into the HTML body of your mailing.

MessageGears Function

Code

Trackable Link

<a href="${Gears.track(url, [name])}">Click Here</a>

Microsite

<a href="${Gears.microsite()}">Click here to view this email in a browser</a>

Unsubscribe

<a href="${Gears.unsubscribe()}">Click here to Unsubscribe</a>

FreeMarker Directives

FreeMarker Directives contains a set of frequently-used FreeMarker commands used to personalize messages. Clicking on an item copies the code into your clipboard, which can then be pasted into the HTML body of your mailing.

FreeMarker Directive

Code

assignment

<#assign name=value>

if/else block

<#if condition>

...

</#if>

For-each loop

<#list widgets as widget>

...

</#list>

function

<#function name param1 param2 ... paramN>

...

<#return returnValue>

...

</#function>

macro

<#macro name param1 param2 ... paramN>

...

<#nested loopvar1, loopvar2, ..., loopvarN>

...

<#return>

...

</#macro>

switch block

<#switch value>

<#case refValue1>

...

<#break>

<#case refValue2>

...

<#break>

...

<#case refValueN>

...

<#break>

<#default>

...

</#switch>

Additional FreeMarker resources can be found here:

http://freemarker.org

The Real-Time Activity Feedservice provides a way to simply and easily consume account activity data in real-time as events (clicks, opens, bounces, etc.) occur. This can be extremely useful for applications using MessageGears that need to capture their activity data more frequently than once a day (i.e. for a job dashboard).

The data is formatted using exactly the same XML structure as the AccountActivity API results. The only difference is that the data will come from a queue in many small XML payloads.

The settings for Real-Time Event tracking can be accessed via Portal:

Navigate to Account

Click to open a specific account

Edit Account Settings

Real-Time Event Settings with credentials are located in the bottom half of the page.

Here you can check the boxes for the events you want to track, and access the credentials for connecting to your MessageGears event queue.

We have documentation about working with that event queue on our Developer Documentation Via our RealTimeAccountActivity Feed.

Amazon Web Services (AWS) also provides extensive documentation about working with the Simple Queue Service (SQS) here: https://aws.amazon.com/sqs/

Between those two documentation sources, you should be all set for building your integration to keep track of real-time event activity from your MessageGears account. Feel free to contact Support with any questions or if you need troubleshooting help while working with the Real-Time Activity Feed.

This service provides a way to simply and easily consume account activity data in real-time as events (clicks, opens, bounces, etc.) occur. This can be extremely useful for applications using MessageGears that need to capture their activity data more frequently than once a day (i.e. for a job dashboard). The data is formatted using exactly the same XML structure as the AccountActivity API results. The only difference is that the data will come from a queue in many small XML payloads.

XSD Location

For a detailed list of all response values, refer to the XSD file below.

https://api.messagegears.net/3.1/WebService?Action=XSD

Deprecated Versions

v3.0 (unchanged in 3.1)

Implementation

Amazon provides their Simple Queue Service as a way to easily and securely transfer data using their API.

Response Values

Common Response Elements (present for all activity types)

Element Name

Description

ActivityItems

The root element of the XML response.

RequestId

The MessageGears request id of the job of which the activity items belongs.

CorrelationId

The correlation id provided with the invocation of this job, if supplied. This field allows you to supply your own job id. This ID is designed to make it easier to match events coming out of MessageGears with the job they belong to in your own system.

ActivityId

The unique activity id for an individual activity item.

Timestamp

The time that the event/activity item occurred.

EmailAddress

The email address of the recipient responsible for the activity item.

IpAddress

The ip address that generated the activity.

Click the Activity Types below to view more about each activity response, including example responses and complete response elements.

Click Activity Response

<ActivityItems>

<ClickActivity>

<RequestId>t25710-07bc4beb-34de-44d1-85b0-d27628a78b2c</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-14T15:50:19.491-04:00</Timestamp>

<IpAddress>74.60.196.56</IpAddress>

<UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>

<Url>http://www.mycompany.com</Url>

<UrlName>Home Page</UrlName>

<Microsite>true</Microsite>

</ClickActivity>

</ActivityItems>

Element Name

Description

ClickActivity

The element containing all the click information. This is a repeating element, one for each click event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Url

The URL of the clicked link.

UrlName

The name (if any) of the link you provided in the template when the link was made trackable.

Microsite

Will be set to "true" if this event originated from a microsite version of an email message.

Open Activity Response

<ActivityItems>

<OpenActivity>

<RequestId>t25710-07bc4beb-34de-44d1-85b0-d27628a78b2c</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-14T15:49:16.064-04:00</Timestamp>

<IpAddress>74.60.196.56</IpAddress>

<UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>

<Microsite>true</Microsite>

</OpenActivity>

</ActivityItems>

Element Name

Description

OpenActivity

The element containing all the open information. This is a repeating element, one for each open event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Microsite

Will be set to “true” if this event originated from a microsite version of an email message.

Delivery Activity Response

<ActivityItems>

<DeliveredMessageActivity>

<RequestId>t25610-3147e501-c83f-42a5-b638-c476e1237a65</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-13T18:51:00.000-04:00</Timestamp>

<IpAddress>74.125.47.27</IpAddress>

</DeliveredMessageActivity>

</ActivityItems>

Element Name

Description

DeliveredMessageActivity

The element containing all the delivery information. This is a repeating element, one for each email delivered for the specified day.

Bounce Activity Response

<ActivityItems>

<BouncedMessageActivity>

<RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-13T19:10:54.000-04:00</Timestamp>

<Category>Invalid Recipient</Category>

<CategoryCode>10</CategoryCode>

<Details>550-5.1.1 The email account that you tried to reach does not exist.</Details>

<IpAddress>74.125.47.27</IpAddress>

</BouncedMessageActivity>

</ActivityItems>

Element Name

Description

BouncedMessageActivity

The element containing all the bounce information. This is a repeating element, one for each bounce event for the specified day.

Category

A general category of the bounce.

CategoryCode

A unique code that identifies the category of the bounce.

Details

The detailed bounce message.

Bounce Categories

Please remove all bounces of type 10 and 30. Failure to do so may negatively impact your inbox performance with the various ISPs.

Category

Category Code

Description

Undetermined

1

The response text could not be identified.

Invalid Recipient

10

The recipient is invalid.

Soft Bounce

20

The message soft bounced.

DNS Failure

21

The message bounced due to a DNS failure.

Mailbox Full

22

The message bounced due to the remote mailbox being over quota.

Too Large

23

The message bounced because it was too large for the recipient.

Timeout

24

The message timed out.

Admin Failure

25

The message was failed by configured policies.

Generic Bounce: No RCPT

30

No recipient could be determined for the message.

Generic Bounce

40

The message failed for unspecified reasons.

Mail Block

50

The message was blocked by the receiver.

Spam Block

51

The message was blocked by the receiver as coming from a known spam source.

Spam Content

52

The message was blocked by the receiver as spam.

Prohibited Attachment

53

The message was blocked by the receiver because it contained an attachment.

Relay Denied

54

The message was blocked by the receiver because relaying is not allowed.

Transient Failure

70

Message transmission has been temporarily delayed.

Invalid Email Syntax

110

The message has a malformed/invalid email address.

Hardbounce Suppression

130

The message is a known-bad email address and has hard-bounces with a category 10 or 30 in the past. It was suppressed from sending to protect IP reputation with the ISP.

Unsubscribe Suppression

131

The recipient of the message has unsubscribed from a message from your account in the past. It was suppressed from sending to protect your sending reputation.

Fbl Suppression

132

The recipient of the message has filed a spam complaint with your account in the past. It was suppressed from sending to protect your sending reputation.

Complainer Suppression

133

The recipient of the message is a known complainer. It was suppressed from sending to protect your sending reputation.

Domain Suppression

134

The recipient domain is not allowed. It was suppressed from sending to protect your sending reputation.

Role Suppression

135

The recipient address is not allowed. It was suppressed from sending to protect your sending reputation.

Unsubscribe Activity Response

<ActivityItems>

<UnsubActivity>

<RequestId>t25810-eec987c5-085b-4d40-a4ce-24a5850638a5</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-15T16:14:46.878-04:00</Timestamp>

<IpAddress>128.234.11.12</IpAddress>

<UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>

</UnsubActivity>

</ActivityItems>

Element Name

Description

UnsubActivity

The element containing all the unsub information. This is a repeating element, one for each open event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Microsite

Will be set to “true” if this event originated from a microsite version of an email message.

Spam Complaint Activity Response

<ActivityItems>

<SpamComplaintActivity>

<RequestId>t25810-eec987c5-085b-4d40-a4ce-24a5850638a5</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-15T16:14:46.878-04:00</Timestamp>

<Isp>gmail.com</Isp>

</SpamComplaintActivity>

</ActivityItems>

Element Name

Description

SpamComplaintActivity

The element containing the Spam Complaint information. This is a repeating element, one for each complaint received for the specified day.

Isp

The domain part of the recipient’s email address.

Job Error Activity Response

<ActivityItems>

<JobErrorActivity>

<RequestId>t25710-9540c8d8-aa5d-44d7-a9ef-a334072df515</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<Timestamp>2010-09-14T13:20:36.994-04:00</Timestamp>

<JobError>

<ErrorCode>Transfer Error</ErrorCode>

<ErrorMessage>AmazonClientException retrieving file: s3://mycompany/myfile.txt - The specified key does not exist.</ErrorMessage>

</JobError>

</JobErrorActivity>

</ActivityItems>

Element Name

Description

JobErrorActivity

The element containing theJob Error information. This is a repeating element, one for each job that failed to be processed for the specified day.

JobError

A repeating element, one for each error that occurred.

ErrorCode

A general error code for the failure.

ErrorMessage

A detailed error description.

Render Error Activity Response

<ActivityItems>

<RenderErrorActivity>

<RequestId>t25610-0b74f4c6-fe21-411f-bba9-82818bf1c31b</RequestId>

<CorrelationId>My Job Id: 101010</CorrelationId>

<ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>

<EmailAddress>[email protected]</EmailAddress>

<Timestamp>2010-09-13T19:13:46.220-04:00</Timestamp>

<RenderErrors>

<RenderError>

<ErrorCode>Template merge exception</ErrorCode>

<ErrorMessage>Error on line 1, column 10 in SUBJECT Expecting a string, date or number here, Expression Recipient.FirstNamex is instead a freemarker.ext.dom.NodeListModel</ErrorMessage>

</RenderError>

</RenderErrors>

</RenderErrorActivity>

</ActivityItems>

Element Name

Description

RenderErrorActivity

The element containing the error information regarding the rendering of an email message. This is a repeating element, one for each email that failed to be rendered for the specified day.

Erro Code

A general error code for the failure.

ErrorMessage

A detailed error description.

Programming Examples

Java SDK

C# SDK

Java SDK

package com.messagegears.sdk.examples;

import com.messagegears.sdk.v3_1.BouncedMessageActivity;

import com.messagegears.sdk.v3_1.ClickActivity;

import com.messagegears.sdk.v3_1.DeliveredMessageActivity;

import com.messagegears.sdk.v3_1.JobErrorActivity;

import com.messagegears.sdk.v3_1.OpenActivity;

import com.messagegears.sdk.v3_1.RenderErrorActivity;

import com.messagegears.sdk.v3_1.SpamComplaintActivity;

import com.messagegears.sdk.v3_1.UnsubActivity;

import com.messagegears.sdk.MessageGearsListener;

import com.messagegears.sdk.aws.MessageGearsAwsProperties;

import com.messagegears.sdk.aws.MessageGearsAwsQueuePoller;

import com.messagegears.sdk.output.ScreenWriter;

public class ActivityFeedExample implements MessageGearsListener {

public static final String MY_AWS_ACCOUNT_ID = "place your aws account id here";

public static final String MY_AWS_SECRET_KEY = "place your aws secret key here";

public static final String MY_AWS_QUEUE = "place your sqs queue url here";

public static void main (String[] args) {

// Create the AWS properties object

MessageGearsAwsProperties props = new MessageGearsAwsProperties();

props.setMyAwsAccountKey(MY_AWS_ACCOUNT_ID);

props.setMyAwsSecretKey(MY_AWS_SECRET_KEY);

props.setMyAwsEventQueueUrl(MY_AWS_QUEUE);

// Create an object of this listener class and start the poller passing in the listener

ActivityFeedExample listener = new ActivityFeedExample();

MessageGearsAwsQueuePoller poller = new MessageGearsAwsQueuePoller(props, listener);

poller.start();

}

public void onOpen(OpenActivity activity) {

ScreenWriter.print(activity);

}

public void onClick(ClickActivity activity) {

ScreenWriter.print(activity);

}

public void onBounce(BouncedMessageActivity activity) {

ScreenWriter.print(activity);

}

public void onDelivery(DeliveredMessageActivity activity) {

ScreenWriter.print(activity);

}

public void onSpamComplaint(SpamComplaintActivity activity) {

ScreenWriter.print(activity);

}

public void onJobError(JobErrorActivity activity) {

ScreenWriter.print(activity);

}

public void onRenderError(RenderErrorActivity activity) {

ScreenWriter.print(activity);

}

public void onUnsub(UnsubActivity activity) {

ScreenWriter.print(activity);

}

}

C# SDK

using System;

using MessageGears.Model.Generated;

using MessageGears.EventQueue;

namespace MessageGears.Examples

{

public class ActivityFeedExample : MessageGearsListener

{

public const String MY_AWS_ACCOUNT_ID = "place your aws account id here";

public const String MY_AWS_SECRET_KEY = "place your aws secret key here";

public const String MY_AWS_QUEUE = "place your sqs queue url here";

public static void Main ()

{

// Create the AWS properties object

MessageGearsAwsProperties props = new MessageGearsAwsProperties();

props.MyAWSAccountKey = MY_AWS_ACCOUNT_ID;

props.MyAWSSecretKey = MY_AWS_SECRET_KEY;

props.MyAWSEventQueueUrl = MY_AWS_QUEUE;

// Create an object of this listener class and start the poller passing in the listener

ActivityFeedExample listener = new ActivityFeedExample();

MessageGearsAwsQueuePoller poller = new MessageGearsAwsQueuePoller(props, listener);

poller.Start();

}

public void OnOpen(OpenActivity activity)

{

Console.WriteLine("***** Open Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine("UserAgent: " + activity.UserAgent);

Console.WriteLine();

}

public void OnClick(ClickActivity activity)

{

Console.WriteLine("***** Click Event Received: " + activity.ActivityId);

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine("Url: " + activity.Url);

Console.WriteLine("UrlName: " + activity.UrlName);

Console.WriteLine("UserAgent: " + activity.UserAgent);

Console.WriteLine();

}

public void OnBounce(BouncedMessageActivity activity)

{

Console.WriteLine("***** Bounce Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("Category: " + activity.Category);

Console.WriteLine("CategoryCode: " + activity.CategoryCode);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("Details: " + activity.Details);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("MessageSize: " + activity.MessageSize);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine();

}

public void OnDelivery(DeliveredMessageActivity activity)

{

Console.WriteLine("***** Delivery Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("MessageSize: " + activity.MessageSize);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine();

}

public void OnSpamComplaint(SpamComplaintActivity activity)

{

Console.WriteLine("***** Spam Complaint Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("Isp: " + activity.Isp);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Subject: " + activity.Subject);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine();

}

public void OnJobError(JobErrorActivity activity)

{

Console.WriteLine("***** Job Error Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("JobError: " + activity.JobError);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine();

}

public void OnRenderError(RenderErrorActivity activity)

{

Console.WriteLine("***** Render Error Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RenderErrors: " + activity.RenderErrors);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine();

}

public void OnUnsub(UnsubActivity activity)

{

Console.WriteLine("***** Unsub Event Received");

Console.WriteLine("ActivityId: " + activity.ActivityId);

Console.WriteLine("CorrelationId: " + activity.CorrelationId);

Console.WriteLine("EmailAddress: " + activity.EmailAddress);

Console.WriteLine("IpAddress: " + activity.IpAddress);

Console.WriteLine("RecipientId: " + activity.RecipientId);

Console.WriteLine("RequestId: " + activity.RequestId);

Console.WriteLine("Timestamp: " + activity.Timestamp);

Console.WriteLine("UserAgent: " + activity.UserAgent);

Console.WriteLine();

}

}

}

Transactional Content Retrieval is used to render a delivered transactional job or campaign.

Deprecated Versions

(none)

Required Parameters

Parameter

Description

Action

TransactionalContentRetrieval

AccountId

The MessageGears account id to which this item belongs.

ApiKey

A secret key only known by you. Keep this key confidential.

OriginalRequestId

The request id of the transactional job or campaign being retrieved

Response Values

Parameter

Data Type

Description

OriginalRequestId

String

The request id of the retrieved content

FromAddress

String

The fully rendered From Address

FromName

String

The fully rendered From Name

SubjectLine

String

The fully rendered Subject Line

TextContent

String

The fully rendered Text content

HtmlContent

String

The fully rendered HTML content

RecipientId

String

(Optional) The recipient id of the recipient used to render the content

Name

String

(Optional) The name of the attached content

ContentType

String

(Optional) The content type of the attached content

CorrelationId

String

(Optional) The correlation id of the content

JobCategory

String

(Optional) The job category of the content

Programming Examples

REST

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=TransactionalContentRetrieval

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&OriginalRequestId=t20815-868efa36-676c-46dc-a0ab-c24cad422621

Success Response

<TransactionalContent xmlns="http://messagegears.com/3.1/webService">

<RequestId>n20915-44de2477-cd85-4d55-b906-2ca59d2d939d</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

<OriginalRequestId>t20815-868efa36-676c-46dc-a0ab-c24cad422621</OriginalRequestId>

<FromAddress>[email protected]</FromAddress>

<FromName>MessageGears</FromName>

<SubjectLine>MessageGears - Reliable Message Delivery</SubjectLine>

<TextContent></TextContent>

<HtmlContent><html>

<body>

<h1>MessageGears</h1>

<p>Reliable Message Delivery</p>

<p>Be sure to visit <a href="http://www.messagegears.com">www.messagegears.com</a> for more information.</p>

</body>

</html>

</HtmlContent>

<CorrelationId>CustomerPortal</CorrelationId>

<JobCategory></JobCategory>

<Attachments>

<Attachment>

<Name>Company Logo</Name>

<ContentType>image/png</ContentType>

</Attachment>

</Attachments>

</TransactionalContent>

Failure Response (Render Errors)

<TransactionalContent xmlns="http://messagegears.com/3.1/webService">

<RequestId>n20915-fcfd3ada-bbf9-42cb-8b30-6b6c30690850</RequestId>

<Result>REQUEST_FAILED</Result>

<RenderErrors>

<RenderError>

<ErrorCode>com.messagegears.core.templating.TemplateMergeException</ErrorCode>

<ErrorMessage>Rendering Error; nested exception is freemarker.core.NonStringException: Error on line 1, column 14 in SUBJECT

</RenderError>

</RenderErrors>

<OriginalRequestId>t20815-868efa36-676c-46dc-a0ab-c24cad422621</OriginalRequestId>

</TransactionalContent>

Java SDK

Click here for more information on using the MessageGears Java SDK

package com.messagegears.sdk.examples;

import com.messagegears.sdk.MessageGearsClient;

import com.messagegears.sdk.MessageGearsProperties;

import com.messagegears.sdk.model.request.TransactionalContentRetrievalRequest;

import com.messagegears.sdk.output.ScreenWriter;

import com.messagegears.sdk.v3_1.TransactionalContent;

public class TransactionalContentRetrievalExample {

public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void main(String[] args) {

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);

props.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

// Create the MessageGears client object

MessageGearsClient client = new MessageGearsClient(props);

TransactionalContentRetrievalRequest request = new TransactionalContentRetrievalRequest();

request.setOriginalRequestId("t20815-868efa36-676c-46dc-a0ab-c24cad422621");

TransactionalContent response = client.transactionalContentRetrieval(request);

// Print the result

ScreenWriter.printResponse(response);

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;

using System.IO;

using MessageGears;

using MessageGears.Model;

using MessageGears.Model.Generated;

namespace MessageGears.Examples

{

public class TransactionalContentRetrievalExample

{

public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void Main ()

{

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;

props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

// Create the MessageGears client object

MessageGearsClient client = new MessageGearsClient(props);

TransactionalContentRetrievalRequest request = new TransactionalContentRetrievalRequest();

request.OriginalRequestId = "t20815-868efa36-676c-46dc-a0ab-c24cad422621";

TransactionalContentRetrievalResponse response = client.TransactionalContentRetrieval(request);

// Print the result

client.PrintResponse(response);

}

}

}

ForwardToAFriend is used to send a single email to a single email address, including a copy of a message previously sent through the MessageGears platform. First a Campaign must be created by following the instructions here. The Campaign contains most of the information necessary to render the message, except the recipient data needed to render and send the message. The ForwardToAFriend API requires that a CampaignId be provided with the request, as well as the original recipient token of specifying the content to be forwarded and the recipient data used to render and send the message.

The RecipientToken for a recipient can be referenced in the HTML or Text content of a message as "${Gears.recipientToken()}".

As an example, a link such as:

http://mywebpage.com/forwardtoafriend.html?recipientToken=${Gears.recipientToken()}

should provide your service with the parameters necessary to make a ForwardToAFriend request.

When designing a campaign, the following items will be available as ContextData XML for reference in the forwarded message:

<OriginalMessage>

<FromName>original rendered FromName</FromName>

<FromAddress>original rendered FromAddress</FromAddress>

<Subject>original rendered Subject</Subject>

<Html>original rendered Html</Html>

<Text>original rendered Text</Text>

<ReplyTo> original rendered Reply To</ReplyTo>

</OriginalMessage>

The Campaign used for ForwardToAFriend may reference these fields in any renderable field such as:

<html>

<body>

Hello ${Recipient.FirstName},

Here's the original message!

<hr>

<#assign originalContent = OriginalMessage.Html?interpret>

<@originalContent />

</body>

</html>

Additionally, it is possible to render the original content differently when in a Forward To A Friend context. A boolean variable, "${Gears.isForwardToAFriend}", is accessible to help remove sensitive content, such as account information or unsubscribe links from the forwarded content.

Deprecated Versions

(none)

Required Parameters

Parameter

Personalizable

Description

Action

TransactionalCampaignSubmit

AccountId

The MessageGears account id to which this item belongs.

ApiKey

A secret key only known by you. Keep this key confidential.

CampaignId

The CampaignId of the campaign to be used to render the message. This Id is displayed when creating and promoting a campaign.

RecipientXml

The XML for a single recipient supplied in the prescribed format.

Click here for more information.

RecipientToken

The recipient token provided by MessageGears for the content to be forwarded.

Optional Parameters

Parameter

Personalizable

Description

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.

Programming Examples

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=ForwardToAFriend

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&CampaignId=22222222

&RecipientXml=<Recipient><EmailAddress>[email protected]</EmailAddress></Recipient>

&RecipientToken=specifiedrecipienttoken

Response

<ForwardToAFriendResponse>

<RequestId>o23110-a9e77b7c-c980-4ff5-8ede-546fbe0bad66</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

</ForwardToAFriendResponse>

AccountSummary is used to check the activity that occurred across all jobs (both transactional and bulk) for a given date.

DeprecatedVersions

v3.0 (unchanged in v3.1)

RequiredParameters

Parameter

Description

Action

AccountSummary

AccountId

The MessageGears account id to which this item belongs.

ApiKey

A secret key only known by you. Keep this key confidential.

ActivityDate

The date of the summary data to be retrieved. Must be in the format of yyyy-MM (for monthly totals) or yyyy-MM-dd (for daily totals). All data will be summarized in EDT.

Response Values

Parameter

Data Type

Description

ActivityDate

Date

Confirmation of the date that was supplied in the request.

Messages

Integer

The total number of email message that were submitted to the service for processing for both transactional and bulk jobs.

Clicks

Integer

The total number of trackable links that were clicked.

Opens

Integer

The total number of messages that were opened.

Bounces

Integer

The total number of messages that were confirmed as undelivered.

Deliveries

Integer

The total number of messages that were successfully delivered.

Unsubscribes

Integer

The total number of unsubscribe requests received. This includes any optional MessageGears "unsubscribe" links, as well as "list unsubscribe" headers.

SpamComplaints

Integer

The total number of times recipients clicked the "report spam" button, or sent their messages to the MessageGears abuse mailbox.

RenderErrors

Integer

The total number of messages that could not be delivered as a result of errors in the message content. This usually occurs when there is syntax error in the Freemarker or Velocity script (if any) contained in the message content.

Programming Examples

REST

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=AccountSummary

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&ActivityDate=2010-07-04

Response

<AccountSummaryResponse>

<RequestId>71d7261e-bbf7-487d-b201-6d3557370cd2</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

<AccountSummary>

<ActivityDate>2010-07-04</ActivityDate>

<Messages>1000000</Messages>

<Clicks>123231</Clicks>

<Opens>152323</Opens>

<Bounces>1283</Bounces>

<Unsubsribes>0</Unsubsribes>

<Deliveries>998121</Deliveries>

<SpamComplaints>2</SpamComplaints>

<RenderErrors>0</RenderErrors>

</AccountSummary>

</AccountSummaryResponse>

Java SDK

Click here for more information on using the MessageGears Java SDK

package com.messagegears.sdk.examples;

import java.util.Date;

import com.messagegears.sdk.v3_1.AccountSummaryResponse;

import com.messagegears.sdk.MessageGearsClient;

import com.messagegears.sdk.MessageGearsProperties;

import com.messagegears.sdk.model.request.AccountSummaryRequest;

import com.messagegears.sdk.output.ScreenWriter;

public class AccountSummaryExample {

public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void main(String[] args) {

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);

props.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

// Create the MessageGears client object

MessageGearsClient client = new MessageGearsClient(props);

// Get the current date, or set to the date desired

Date date = new Date();

AccountSummaryRequest request = new AccountSummaryRequest();

request.setDate(date);

// Invoke the AccountSummary API

AccountSummaryResponse response = client.accountSummary(request);

// Print the result

ScreenWriter.printResponse(response);

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;

using System.IO;

using MessageGears;

using MessageGears.Model;

using MessageGears.Model.Generated;

namespace MessageGears.Examples

{

public class AccountSummaryExample

{

public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void Main ()

{

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;

props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

// Create the MessageGears client object

MessageGearsClient client = new MessageGearsClient(props);

// Get the current date, or set to the date desired

DateTime dateTime = DateTime.Today;

// Invoke the AccountSummary API

AccountSummaryResponse response = client.AccountSummary(dateTime);

// Print the result

client.PrintResponse(response);

}

}

}

While Snippets are meant to be used within a single template, Shared Content is created with multiple templates in mind and can be used in any number of different templates.

Like Snippets, the Shared Content Library is a repository of macros, functions, HTML, and other coded content for use within templates. Since Shared Content is managed as an asset, each can be organized into folders and have differing Permissions applied.

The code for including Shared Content in a template looks like this:

<#include '/global/yoursharedcontentname’>

Add Shared Content

To add new Shared Content, navigate to Content > Shared Content, click the Actions drop-down menu, and select "Add Shared Content". Provide a name for the Shared Content, as well as a description (if desired), then click "Save".

After saving, you'll see the Shared Content edit screen. Here you can create or edit your content, import a file, and test the shared content against a variety of different templates.

Once a piece of Shared Content is created, it will be available to reference in any template within your organization.

SMTP Relay

The SMTP Relay allows you to send email through MessageGears as if it were a standard SMTP server. You can send email to our SMTP service directly from your application, or you can configure your local SMTP server to deliver email through our service. This option allows easy integration with our service while still providing all of the bounce, spam complaint, and open tracking features provided by our Web Services APIs.

Configure your SMTP server or Email Client with the following:

Service Address:

smtp.messagegears.net

Ports:

25 or 2525 (Plain and TLS)

SSL Port:

4525

SMTP User Id

your MessageGears Account Id

SMTP Password

your MessageGears API Key

All accounts must supply a user id and password in order to access the SMTP service. If multiple recipients are specified in the “TO” address, each recipient will receive a separate message.

Currently, the MessageGears SMTP Relay does not support Attachments, or CC and BCC addresses. Please use the Web Services APIs to send attachments.

2017 MessageGears Documentation. All rights reserved.

MessageGears .NET SDK

The MessageGears .NET SDK makes integration seamless. The SDK eliminates the need to write any web services code and enables you to access all of our services using the .NET. It also provides access to Amazon’s S3 and SQS services to make it easy to exchange files with MessageGears.

C# Code Examples

C# sample code is provided with each web service description

NuGet Package Manager

The SDK is available for download from NuGet Gallery.

NuGet Gallery for MessageGears SDK

SDK Downloads

Or you can download and install each DLL by hand with the links below.

MessageGears Code .NET DLL

Amazon AWS DLL

Log4Net DLL

Open Source SDK

We’ve made the source code to our .NET SDK available to you. You’re welcome to write your own code to access our web services natively using our code as a reference.

C# SDK Source Code on GitHub

2017 MessageGears Documentation. All rights reserved.

This field is a user-defined set of XML data that is made accessible to the template for personalization of the message. The following rules apply:

It must be well-formed XML

It must start with a <Recipient> element.

It must contain a <EmailAddress> element

This is the email address to whom the message will be sent.

It may contain a <RecipientId> element.

It may contain an unlimited number ofcustomer elements to be used by the email templates for personalization.

Examples

Minimum

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

</Recipient>

Specifying a Recipient Id

The optional <RecipientId> element has special meaning. When it is present, it will be passed back to you in the detailed activity data (clicks, opens, bounces, etc.). This is very helpful to you if you have your own unique identifier for your customers. When you process you response/activity data, you can store the activity data using your identifier instead of using email address.

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

<RecipientId>FF123456789</RecipientId>

</Recipient>

We recommend against using sensitive data (like SSN, etc.) as the recipient id as this data will be encoded in click and open URLs.

Data for a Highly Personalized Template

All elements of the recipient XML may be used to personalize your email content.

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

<FirstName>Joe</FirstName>

<LastName>Last Name</LastName>

<Gender>M</Gender>

<Order>

<OrderNumber>123456</OrderNumber>

<Item>

<SKU>2304974353</SKU>

<Desc>Hammer</Desc>

<Price>25</Price>

<Qty>2</Qty>

</Item>

<Item>

<SKU>34354545</SKU>

<Desc>Saw</Desc>

<Price>19</Price>

<Qty>1</Qty>

</Item>

</Order>

</Recipient>

Attachments are passed in to MessageGears using URLs. Up to five files can be attached to a message. Each attachment has three possible values as specified below. Each field must have a suffix which indicates which attachment number it represents (1 through 5).

Field Name

Description

AttachmentUrl.n

If this field is present, the file will be retrieved and attached to the message(s) generated by the API call. Exactly one of AttachmentUrl or AttachmentContent must be provided for an attachment.

Refer tothe documentation regarding referencing remote files for more information.

AttachmentContent.n

If this field is present, the file has been provided to the API call in the form of a base-64 encoded string. Exactly one of AttachmentUrl or AttachmentContent must be provided for an attachment.

AttachmentName.n

This is a required field (if a url is specified above) and is used to give a friendly name for the attachment.

AttachmentContentType.n

This is also a required field (if a url is specified above) and is used to help the email client associate an application with the attached file (e.q. Excel will launch and load the attached file when the recipient double-clicks on the attachment). Some common context types are:

application/pdf

image/jpeg

text/plain

application/msword

Click here for more about commonly used content-types.

We want to make you aware of upcoming maintenance that may impact your MessageGears service.

On Saturday, April 22, 2017, from 8:00 a.m. - 8:00 p.m. EDT, MessageGears will be performing data warehouse maintenance. During this time, the updating of some analytics data maybe delayed-- specifically, reporting of unique opens, unique clicks, and click heat maps maybe impacted.

Data collected during this time will become available after the maintenance is completed. All other functions and services will operate normally during the maintenance window.

Please contact MessageGears Customer Support at [email protected] if you have any questions.

Thank you for your attention and understanding.

When you configure the auto-tracking of links in your HTML content, all links will be tracking. If you wish to turn off tracking of one or more individual links, you would use the following syntax in your content:

<a href=" http://www.messagegears.com " autotrack="false">>

Conversely, you could configure auto-tracking of links to be off by default and you could manually configure individual links to be tracking using the following syntax:

<a href=" http://www.messagegears.com " autotrack="true">>

Using the Activity link in Portal's top navigation, you will access Address Search, which allows you to enter a recipient email address to check suppression-relatedtypes of activity for that address.

Hard bounce

Unsubscribe

Spam complaint

All requests to MessageGears require you to authenticate with your Account ID and API Key. Think of your Account ID as your username, and your API Key as your password for MessageGears.

Your Account ID is a 8 character string which identifies your account when making requests to the MessageGears API.

Your API Key is a 32 character string that is your password for the MessageGears API. You should always keep your APIKey private.

There are two ways to access these credentials - in an aggregate list or individually.

Aggregate List

User Profile icon in the top right corner, and selectingSMTP & API Credentials from the drop down.

This will provide you with a completelist of all of the API credentials for all accounts (sub-accounts) within your overall MessageGears customer account.

Individual Account Credentials

To access individual account's API keys, first click Account in the top navigation of Portal.

From the Account page, locate the Accounts grid and click the Id of the account you want to get credentials for. If you have many accounts, you may need to use the search box, which will populate results as you type.

On the individual account's page, the API key is available in the Account Settings box. Click the (show) link to display the key.

From the Account Settings > Edit page you can also view the API Key, and reset it if the credential is compromised.

There are a lot of different reasons an email may bounce, and understanding whether the bounce was preventable or not can provide insight into improving the overall deliverability of your email.

Please remove all bounces of type 10 and 30. Failure to do so may negatively impact your inbox performance with the various ISPs.

Bounce Categories

Category

Category Code

Description

Undetermined

1

The response text could not be identified.

Invalid Recipient

10

The recipient is invalid.

Soft Bounce

20

The message soft bounced.

DNS Failure

21

The message bounced due to a DNS failure.

Mailbox Full

22

The message bounced due to the remote mailbox being over quota.

Too Large

23

The message bounced because it was too large for the recipient.

Timeout

24

The message timed out.

Admin Failure

25

The message was failed by configured policies.

Generic Bounce: No RCPT

30

No recipient could be determined for the message.

Generic Bounce

40

The message failed for unspecified reasons.

Mail Block

50

The message was blocked by the receiver.

Spam Block

51

The message was blocked by the receiver as coming from a known spam source.

Spam Content

52

The message was blocked by the receiver as spam.

Prohibited Attachment

53

The message was blocked by the receiver because it contained an attachment.

Relay Denied

54

The message was blocked by the receiver because relaying is not allowed.

Transient Failure

70

Message transmission has been temporarily delayed.

Invalid Email Syntax

110

The message has a malformed/invalid email address.

Hardbounce Suppression

130

The message is a known-bad email address and has hard-bounces with a category 10 or 30 in the past. It was suppressed from sending to protect IP reputation with the ISP.

Unsubscribe Suppression

131

The recipient of the message has unsubscribed from a message from your account in the past. It was suppressed from sending to protect your sending reputation.

Fbl Suppression

132

The recipient of the message has filed a spam complaint with your account in the past. It was suppressed from sending to protect your sending reputation.

Complainer Suppression

133

The recipient of the message is a known complainer. It was suppressed from sending to protect your sending reputation.

Domain Suppression

134

The recipient domain is not allowed. It was suppressed from sending to protect your sending reputation.

Role Suppression

135

The recipient address is not allowed. It was suppressed from sending to protect your sending reputation.

Sending Profiles allow you to set consistent, reusable Header Field parameters which can be used in multiple templates and campaigns.There are a number of Header Fields specific to message delivery.Sending Profiles allow you to define sets of the following values needed to send from Accelerator:

From Name

From Address

Reply-To (Address)

Subject lines cannot be defined withinSending Profiles.

Personalization

You can personalize each of the previously listed fields.

Example: You could add each recipients's email address to the Subject Line as follows

User ${Recipient.EmailAddress} was updated!

For the email address [email protected], the Subject line displays as:

User [email protected] was updated!

More about Message Header Fields

The From Name and From Address fields map to a single From line in the actual message header. However, on the design side, these components are isolated for convenience because From Address is required and From Name is optional.

Example: A From Name of John Doe and From Address of [email protected] results in the following From header field message display:

John Doe

Reply-To indicates the address that should be used for response messages and maps to the Reply-To message header line.

Adding a Sending Profile

Enter the new Sending Profile Name and From Address.

Select the appropriate Account from the drop-down list. (This account will be the only one able to use this particular Sending Profile for templates and campaigns.)

Optional: Enter Description, From Name, and Reply-To details

Click Save

All of the field entries above, including the Account, can be edited by opening the Sending Profile, then going to Actions > Edit.

The term “Engagement” when used in relation to email references how your recipients are interacting with the emails sent to them. For example, if a recipient is regularly opening your emails and clicking links within them, that is said to be highly-engaged. Low engagement, high complaints, and high unsubscribes can all be indications that there are content issues or deliverability issues with your emails, so monitoring engagement over time is important.

Unsubscribes

Unsubscribing or "opting-out" is the act of a recipient notifying a message sender that they want to be removed from a list and not receiving any future correspondence.

The unsubscribe rate is calculated by the number of unsubscribes received from a specific sent job divided by the number of delivered messages. For example, if a bulk job is delivered to 1000 recipients, and there are 10 unsubscribes, the unsubscribe rate would be 1\%.

Spam Complaints

Spam complaints are logged when a recipient complains directly or marks the message received as spam in their inbox. Spam complaints will result in the complaining recipient being suppressed from receiving future email from that sender.

Spam complaint rate is calculated by the number of complaints received from a specific sent job divided by the number of delivered messages.

Total Open Rate

Total Opens constitutes of every single logged open related to the sent job. This will include opens where a recipient logs multiple opens.

Total open rate is the rate of total opens divided by deliveries.

= total-opens/deliveries * 100

Unique Open Rate

Unique Opens counts only one open per recipient for the specific sent job. This value excludes when a recipient logs multiple opens, and only counts the first one logged.

Unique open rate is the rate of unique opens divided by deliveries.

= unique-opens/deliveries * 100

Total Click Rate

Total Clicks constitutes every logged link click occurring from a specific sent job. This can include multiple clicks on the same link by the same recipient.

Total click rate is the rate of total clicks divided by total opens.

= total-clicks/total-opens * 100

Unique Click Rate

Unique Clicks counts only one link click per link per recipient for the related sent job. This value excludes when a recipient logs multiple clicks on the same link, and only counts the first one logged for each link.

Unique click rate is the rate of unique clicks divided by total opens.

= unique-clicks/total-opens * 100

MessagePreview is used to render a template and return the resulting content. It can be used for testing content before making calls to the bulk or transactional APIs.

Deprecated Versions

v3.0 (November 2010)

Required Parameters

Parameter

Personalizable

Description

Action

MessagePreview

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.

Click here for more information.

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.

Click here for more information regarding the use of OnBehalfOf.

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.

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.

Click here for a full list of available character sets.

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.

Click here for more information.

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.

Click here for more information.

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

Click here for more information.

ContextDataXml

This field is used to supply data to the template that is not directly related to the recipient. For example, this field could contain data about weekly airfare specials by city. The template could then select only the fares that originated from the same city as the recipients home. This helps make it easy to create templates with relevant data for each recipient.

Click here for more information.

Response Values

Parameter

Data Type

Description

FromAddress

String

The fully rendered From Address

FromName

String

The fully rendered From Name

SubjectLine

String

The fully rendered Subject Line

TextContent

String

The fully rendered Text content

HtmlContent

String

The fully rendered HTML content

Spam

boolean

Will return “true” if the SpamScore is >= 5.0 (the default threshold of SpamAssassin)

Score

Number

The SpamAssassin spam score

Points

Number

The numeric value assigned to a rule that was triggered by your email content

RuleName

String

The SpamAssassin rule that was triggered by your email content

Description

String

A description of the rule that was triggered

Click here for a full list of SpamAssassin Rules and Descriptions

MessageGears is currently using version 3.2.5-1 of SpamAssassin

Programming Examples

REST

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=MessagePreview

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&FromName=Customer Support

&[email protected]

&SubjectLine=Message to ${Recipient.FirstName}

&HtmlTemplate=<html>Hello, ${Recipient.FirstName}!</html>

&RecipientXml=<Recipient><EmailAddress>[email protected]</EmailAddress><FirstName>John</FirstName></Recipient>

Success Response

<MessagePreviewResponse>

<RequestId>m311-6cc4d321-fbce-4e86-aa53-c50766f03eaa</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

<PreviewContent>

<FromAddress>[email protected]</FromAddress>

<FromName>Customer Support</FromName>

<SubjectLine>Message to John</SubjectLine>

<TextContent>Hello, John!</TextContent>

<HtmlContent><html>Hello, John!<img src="http://www.messagegears.net/o/1/36686378/m311-6cc4d321-fbce-4e86-aa53-c50766f03eaa/wbua.qbr/nby/pbz"/></html></HtmlContent>

<SpamAssassinReport>

<Spam>false</Spam>

<Score>1.5</Score>

<Requried>5.0</Requried>

<SpamAssassinRules>

<SpamAssassinRule>

<Points>1.5</Points>

<RuleName>HTML_IMAGE_ONLY_04</RuleName>

<Description>BODY: HTML: images with 0-400 bytes of words </Description>

</SpamAssassinRule>

</SpamAssassinRules>

</SpamAssassinReport>

</PreviewContent>

</MessagePreviewResponse>

Failure Response (Rendering Errors)

<MessagePreviewResponse>

<RequestId>m15212-50d85cd9-2d73-4ce4-a458-b5145c1a2e06</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

<RenderErrors>

<RenderError>

<ErrorCode>com.messagegears.core.templating.TemplateMergeException</ErrorCode>

<ErrorMessage>Rendering Error; nested exception is freemarker.core.NonStringException: Error on line 1, column 14 in SUBJECT

</RenderError>

</RenderErrors>

<PreviewContent>

<FromAddress>[email protected]</FromAddress>

<FromName>Customer Support</FromName>

<OnBehalfOfName/>

<OnBehalfOfAddress/>

<ReplyToAddress/>

<SubjectLine>Message to</SubjectLine>

<TextContent/>

<HtmlContent><html>Hello, John!<img src="http://www.messagegears.net/o/1/10179231/m15212-50d85cd9-2d73-4ce4-a458-b5145c1a2e06/wbua.qbr/nby/pbz"/></html></HtmlContent>

<SpamAssassinReport>

<Spam>false</Spam>

<Score>1.5</Score>

<Required>5.0</Required>

<SpamAssassinRules>

<SpamAssassinRule>

<Points>1.5</Points>

<RuleName>HTML_IMAGE_ONLY_04</RuleName>

<Description>BODY: HTML: images with 0-400 bytes of words </Description>

</SpamAssassinRule>

</SpamAssassinRules>

</SpamAssassinReport>

</PreviewContent>

</MessagePreviewResponse>

Java SDK

Click here for more information on using the MessageGears Java SDK

package com.messagegears.sdk.examples;

import com.messagegears.sdk.v3_1.MessagePreviewResponse;

import com.messagegears.sdk.MessageGearsClient;

import com.messagegears.sdk.MessageGearsProperties;

import com.messagegears.sdk.model.request.MessagePreviewRequest;

import com.messagegears.sdk.output.ScreenWriter;

public class MessagePreviewExample {

public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void main(String[] args) {

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);

props.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

// Create the MessageGears client object

MessageGearsClient client = new MessageGearsClient(props);

MessagePreviewRequest request = new MessagePreviewRequest();

request.setAutoTrack(true);

request.setCorrelationId("MyPreviewCorrelationId");

request.setCustomTrackingDomain("http://mycustomtrackingdomain.com/");

request.setFromAddress("[email protected]");

request.setFromName("MessageGears Preview");

request.setHtmlTemplate(getHtmlTemplate());

request.setRecipientXml(getRecipientXml());

request.setOnBehalfOfAddress("[email protected]");

request.setOnBehalfOfName("MessageGears");

request.setReplyToAddress("[email protected]");

request.setSubjectLine("MessageGears Preview API Example");

request.setUnsubscribeHeader(true);

MessagePreviewResponse response = client.messagePreview(request);

// Print the result

ScreenWriter.printResponse(response);

}

private static String getHtmlTemplate() {

return "<html><body>Welcome to MessageGears!<br><br>Be sure to check out our website at" +

"<a href="${Gears.track("http://www.messagegears.com","homepage")}">www.messagegears.com</a>." +

"<br><br>Here is an unsubscribe link: <a href="${Gears.unsubscribe()}">Unsubscribe Me</a>" +

"<br><br>Thanks,<br>The MessageGears Team</body></html>";

}

private static String getRecipientXml() {

return "<Recipient><EmailAddress>[email protected]</EmailAddress>" +

"<RecipientId>recipient123</RecipientId></Recipient>";

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;

using System.IO;

using MessageGears;

using MessageGears.Model;

using MessageGears.Model.Generated;

namespace MessageGears.Examples

{

public class MessagePreviewExample

{

public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void Main ()

{

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;

props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

// Create the MessageGears client object

MessageGearsClient client = new MessageGearsClient(props);

MessagePreviewRequest request = new MessagePreviewRequest();

request.AutoTrack = true;

request.CorrelationId= "MyPreviewCorrelationId";

request.CustomTrackingDomain = "http://mycustomtrackingdomain.com/";

request.FromAddress = "[email protected]";

request.FromName = "MessageGears Preview";

request.HtmlTemplate = getHtmlTemplate();

request.RecipientXml = getRecipientXml();

request.OnBehalfOfAddress = "[email protected]";

request.OnBehalfOfName = "MessageGears";

request.ReplyToAddress = "[email protected]";

request.SubjectLine = "MessageGears Preview API Example";

request.UnsubscribeHeader = true;

MessagePreviewResponse response = client.MessagePreview(request);

// Print the result

client.PrintResponse(response);

}

private static String getHtmlTemplate() {

return "<html><body>Welcome to MessageGears!<br><br>Be sure to check out our website at " +

"<a href="${Gears.track("http://www.messagegears.com","homepage")}">MessageGears" +

"</a>.<br><br>Here is an unsubscribe link: <a href="${Gears.unsubscribe()}">Unsubscribe</a>" +

"<br><br>Thanks,<br>The MessageGears Team</body></html>";

}

private static String getRecipientXml() {

return "<Recipient><EmailAddress>[email protected]</EmailAddress>" +

"<RecipientId>You</RecipientId></Recipient> ";

}

}

}

BulkJobSubmit is used to send a email message to a list of one or more recipients. There is no hard limit on the size of the list and millions of emails can be sent from a single invocation of this API. To use this API, you must create an XML file that contains a list of all the recipients and place it on an HTTP server where it can be retrieved by the MessageGears system. Then you make an API call and supply the URL where the recipient file is located along with the HTML and text template data as described below. MessageGears will then retrieve the recipient file and perform a "mail merge" with the supplied content to generate the individual email messages.

Deprecated Versions

v3.0 (November 2010)

Required Parameters

Parameter

Personalizable

Description

Action

BulkJobSubmit

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.

RecipientListXmlUrl

A URL pointing to a file that contains a list of recipient data. The file may be compressed using the "ZIP" or "GZIP" algorithms. Supported protocols are http, https, and Amazon S3. The referenced file must have a ".xml" extension if uncompressed, ".zip" if compressed using ZIP, and ".gz" if compressed using Gzip.

Click here for more information.

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.

Click here for more information regarding the use of OnBehalfOf.

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

Click here for more information regarding attachments.

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

Click here for more information regarding attachments.

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.

Click here for a full list of available character sets.

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.

Click here for more information.

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.

Click here for more information.

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

Click here for more information.

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

Click here for more information regarding custom headers.

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.

Click here for more information.

Programming Examples

REST

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=BulkJobSubmit

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&FromName=Customer Support

&[email protected]

&SubjectLine=Welcome!

&HtmlTemplate=<html>Thank you for enrolling in our support forum.</html>

&TextTemplate=Thank you for enrolling in our support forum.

&RecipientListXmlUrl=http://www.mycompany.com/file/WelcomeRecipients.xml

&TemplateLanguage=FREEMARKER

Response

<BulkJobSubmitResponse>

<RequestId>b23510-82279647-13fa-4930-8338-ec85988b6bed</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

</BulkJobSubmitResponse>

Java SDK

Click here for more information on using the MessageGears Java SDK

package com.messagegears.sdk.examples;

import java.io.File;

import java.io.FileInputStream;

import java.io.IOException;

import java.io.UnsupportedEncodingException;

import org.apache.commons.io.FileUtils;

import com.messagegears.sdk.MessageGearsClient;

import com.messagegears.sdk.MessageGearsProperties;

import com.messagegears.sdk.aws.MessageGearsAwsClient;

import com.messagegears.sdk.aws.MessageGearsAwsProperties;

import com.messagegears.sdk.exception.MessageGearsClientException;

import com.messagegears.sdk.model.request.BulkJobSubmitRequest;

import com.messagegears.sdk.output.ScreenWriter;

import com.messagegears.sdk.v3_1.BulkJobSubmitResponse;

public class BulkJobExample {

public static final String MY_EMAIL_ADDRESS = "place your email address here";

public static final String S3_BUCKET = "place your S3 bucket name here";

public static final String XML_FILE_NAME = "recipients.xml";

public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static final String MY_AWS_ACCOUNT_ID = "place your AWS account id here";

public static final String MY_AWS_SECRET_KEY = "place your AWS secret key here";

public static void main(String[] args) {

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);

props.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

// Create the MessageGears client object

MessageGearsClient client = new MessageGearsClient(props);

// Create a bulk job request

BulkJobSubmitRequest request = new BulkJobSubmitRequest();

// Create a String containing the recipient XML for 2 emails

// You would probably construct this list by querying your database and streaming the XML data to a file.

String recipientListXml =

"<RecipientList>" +

"<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS + "</EmailAddress><FirstName>Recipient 1</FirstName></Recipient>" +

"<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS + "</EmailAddress><FirstName>Recipient 2</FirstName></Recipient>" +

"</RecipientList>";

// Copy the XML to Amazon S3 where it can be retrieved by MessageGears

String recipientFileName = pushRecipientXmlFile(recipientListXml);

// Set the message content

request.setFromName("MessageGears");

request.setFromAddress("[email protected]");

request.setSubjectLine("MessageGears - Reliable Message Delivery");

request.setRecipientListXmlUrl("s3://" + S3_BUCKET + "/" + recipientFileName);

request.setHtmlTemplate("Hello, ${Recipient.FirstName}!");

// Execute the request

BulkJobSubmitResponse response = client.bulkJobSubmit(request);

// Print the result (success or failure)

ScreenWriter.printResponse(response);

}

private static String pushRecipientXmlFile(String recipientListXml) {

// Create the AWS properties object

MessageGearsAwsProperties awsProps = new MessageGearsAwsProperties();

awsProps.setMyAwsAccountKey(MY_AWS_ACCOUNT_ID);

awsProps.setMyAwsSecretKey(MY_AWS_SECRET_KEY);

// Create the AWS client object

MessageGearsAwsClient awsClient = new MessageGearsAwsClient(awsProps);

try {

// write local temp file

File tempFile = new File(XML_FILE_NAME);

FileUtils.writeStringToFile(tempFile, recipientListXml);

// compress temp file

File compressedFile = awsClient.compressFile(tempFile);

// delete the file from s3 since it might already exist

awsClient.deleteS3File(S3_BUCKET, compressedFile.getName());

// upload the compressed xml file to S3

awsClient.putS3File(new FileInputStream(compressedFile), S3_BUCKET, compressedFile.getName());

// cleanup temp file and local compressed file

compressedFile.delete();

tempFile.delete();

return compressedFile.getName();

} catch (UnsupportedEncodingException usee) {

throw new MessageGearsClientException("Unsupported encoding type.");

} catch (IOException e) {

throw new MessageGearsClientException("IOException - Failed to upload recipient list.");

}

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;

using System.IO;

using MessageGears;

using MessageGears.Model;

using MessageGears.Model.Generated;

using MessageGearsAws;

namespace MessageGears.Examples

{

public class BulkSample

{

public const String MY_EMAIL_ADDRESS = "place your email address here";

public const String S3_BUCKET = "place your S3 bucket name here";

public const String XML_FILE_NAME = "recipients.xml";

public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public const String MY_AWS_ACCOUNT_ID = "place your AWS account id here";

public const String MY_AWS_SECRET_KEY = "place your AWS secret key here";

public static void Main ()

{

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;

props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

// Create the MessageGears client object

MessageGearsClient client = new MessageGearsClient(props);

// Create a bulk job request

BulkJobSubmitRequest request = new BulkJobSubmitRequest();

// Create a String containing the recipient XML for 2 emails

// You would probably construct this list by querying your database and streaming XML data to a file.

String recipientListXml =

"<RecipientList>" +

"<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS +

"</EmailAddress><FirstName>Recipient 1</FirstName></Recipient>" +

"<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS +

"</EmailAddress><FirstName>Recipient 2</FirstName></Recipient>" +

"</RecipientList>";

// Copy the XML to Amazon S3 where it can be retrieved by MessageGears

string recipentFile = pushRecipientXmlFile(recipientListXml);

// Set the message content

request.FromName = "MessageGears";

request.FromAddress = "[email protected]";

request.SubjectLine = "MessageGears - Reliable Message Delivery";

request.RecipientListXmlUrl = "s3://" + S3_BUCKET + "/" + recipentFile;

request.HtmlTemplate = "Hello ${Recipient.FirstName}!";

// Execute the request

BulkJobSubmitResponse response = client.BulkJobSubmit(request);

// Print the result (success or failure)

client.PrintResponse(response);

}

private static string pushRecipientXmlFile(String recipientListXml)

{

// Create the AWS properties object

MessageGearsAwsProperties awsProps = new MessageGearsAwsProperties();

awsProps.MyAWSAccountKey = MY_AWS_ACCOUNT_ID;

awsProps.MyAWSSecretKey = MY_AWS_SECRET_KEY;

// Create the AWS client object

MessageGearsAwsClient awsClient = new MessageGearsAwsClient(awsProps);

// write local temp file

File.WriteAllText(XML_FILE_NAME, recipientListXml);

// compress temp file

string compressedFileName = awsClient.CompressFile(XML_FILE_NAME);

// delete the file from s3 since it might already exist

awsClient.DeleteS3File(S3_BUCKET, compressedFileName);

// upload the compressed xml file to S3

awsClient.PutS3File(compressedFileName, S3_BUCKET, compressedFileName);

// cleanup temp file and local compressed file

File.Delete(XML_FILE_NAME);

File.Delete(compressedFileName);

// return the name of the compressed xml recipient file so it can be referenced later

return compressedFileName;

}

}

}

Audit Log

The Audit Log page displays the Audit & Access Activity in a searchable list format, with the most recent activity at the top of the list. Here you can view and sort user activities by timestamp, individual user, and type of activity.

For example, you can view when a particular user logs in, or the creation and modification of particular assets (queries, templates, and campaigns).

Using the search box above the list you can search for particular activities, users, or assets.

SystemInformation

Accelerator captures technical data as the system is configured and updated. The System Information page allows you to view details related to your current technical environment.

The Thumbnail API is used to generate a jpg image representation of HTML or Text content. The image is hosted by MessageGears and can be reference athttp://thumbnails.messagegears.net/<account id>/<image id>.jpg. The Image URL is also returned in the response from a successful API call.

Deprecated Versions

(none)

Required Parameters

Parameter

Description

Action

Thumbnail

AccountId

The MessageGears account id to which this item belongs.

ApiKey

A secret key only known by you. Keep this key confidential.

Content

The HTML or text content to be rendered as an image

ImageId

The base name of the image file to be created. It will be appended with the ".jpg" extension automatically.

ImageSize

The size of the image to be created. Value values are: MICRO, SMALL, SMEDIUM, MEDIUM, LARGE, and GRANDE. The sizes of the images are 64 x 48, 80 x 60, 220 x 165, 232 x 174, 400 x 300, and 800 x 600 respectively.

Programming Examples

REST

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=Thumbnail

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&Content=<html>Hello, World!</html>

&ImageId=12345

&ImageSize=MEDIUM

Response

<ThumbnailResponse>

<RequestId>i3012-ae148ce1-a991-4304-984d-b3b4b0354970</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

<imageUrl>http://thumbnails.messagegears.net/123456789/12345.jpg</imageUrl>

</ThumbnailResponse>

Java SDK

Click here for more information on using the MessageGears Java SDK

package com.messagegears.examples;

import com.messagegears.sdk.MessageGearsClient;

import com.messagegears.sdk.MessageGearsProperties;

import com.messagegears.sdk.model.ThumbnailSize;

import com.messagegears.sdk.model.request.ThumbnailRequest;

import com.messagegears.sdk.output.ScreenWriter;

import com.messagegears.sdk.v3_1.ThumbnailResponse;

public class Thumbnail {

public static final String MY_EMAIL_ADDRESS = "place your email address here";

public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void main(String[] args) {

// Update the properties object containing the necessary properties

MessageGearsProperties properties = new MessageGearsProperties();

properties.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);

properties.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

// Update the main client object

MessageGearsClient client = new MessageGearsClient(properties);

// Update a bulk campaign request

ThumbnailRequest request = new ThumbnailRequest();

// Set the content for the thumbnail

request.setContent("<html>Hello, World!</html>");

// Set the image file name (prefix)

request.setImageId("12345");

// Set the thumbnail image size

request.setThumbnailSize(ThumbnailSize.MEDIUM);

// Execute the request

ThumbnailResponse response = client.thumbnail(request);

// Print the result (success or failure)

ScreenWriter.printResponse(response);

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;

using MessageGears;

using MessageGears.Model;

using MessageGears.Model.Generated;

namespace MessageGears.Sample

{

public class ThumbnailSample

{

// Replace this value with your email address

public const String MY_EMAIL_ADDRESS = "place your email address here";

public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void Main ()

{

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;

props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

// Create the main client object

MessageGearsClient client = new MessageGearsClient(props);

// Create a request

ThumbnailRequest request = new ThumbnailRequest();

// Set the thumbnail image content

request.Content = "<html>Hello, World!</html>";

// Set the image file name prefix

request.ImageId = "12345";

// Set the image size

request.ThumbnailSize = ThumbnailSize.MEDIUM;

// Execute the request

ThumbnailResponse response = client.Thumbnail(request);

// Print the result (success or failure)

Console.WriteLine("Image URL: " + response.imageUrl);

client.PrintResponse(response);

}

}

}

Sample Thumbnail Images

Content = "<html>Hello, World!</html>"

MICRO (64 x 48)

SMALL (80 x 60)

SMEDIUM (220 x 165)

MEDIUM (232 x 174)

LARGE (400 x 300)

GRANDE (800 x 600)

BulkJobSummary is used to check the status of an individual bulk job. A typical use case would be for a dashboard application to poll this API for any active bulk jobs in order to update counters, gauges, and dials on a user interface.

DeprecatedVersions

v3.0 (November 2010)

InputParameters

Parameter

Description

Action

BulkJobSummary

AccountId

The MessageGears account id to which this item belongs.

ApiKey

A secret key only known by you. Keep this key confidential.

BulkJobRequestId

The Request Id of the bulk job to be queried. You can supply this field or the BulkJobCorrelationId, but not both.

BulkJobCorrelationId

The correlation Id of the bulk job to be queried. You can supply this field or the BulkJobRequestId, but not both. This value is provided by the user when the BulkJobSubmit API is called. Querying using this value can be very helpful when building BulkJobSubmit retry logic when and error occurs and you are not sure if the bulk job request was received successfully.

Response Values

Parameter

Data Type

Description

BulkJobRequestId

String

The Request Id of the bulk to be queried. This is simply a confirmation of the bulk job id that was submitted to the service.

Messages

Integer

The total number of email message that were submitted to the service for processing for both transactional and bulk jobs.

Clicks

Integer

The total number of trackable links that were clicked.

Opens

Integer

The total number of messages that were opened.

Bounces

Integer

The total number of messages that were confirmed as undelivered.

Deliveries

Integer

The total number of messages that were successfully delivered.

Unsubscribes

Integer

The total number of unsubscribe requests received. This includes any optional MessageGears "unsubscribe" links, as well as "list unsubscribe" headers.

SpamComplaints

Integer

The total number of times recipients clicked the "report spam" button, or sent their messages to the MessageGears abuse mailbox.

RenderErrors

Integer

The total number of messages that could not be delivered as a result of errors in the message content. This usually occurs when there is syntax error in the Freemarker or Velocity script (if any) contained in the message content.

BulkJobErrors

String

A list of errors experienced in attempting to process the bulk job. These are errors that were experiences after the request was received. Examples of this kind of error include errors retrieving the recipient data file, and errors with the XML content of the recipient data file. Usually, an error of this type prevents the entire job from being processed. The remedy is to simple fix the error and resubmit the entire job via the SendBulkJob API.

CorrelationId

String

The user-defined correlation id that was specified when the job was submitted. It should be a unique value that identifies the job in the customer’s system.

Programming Examples

REST

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=BulkJobSummary

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&BulkJobRequestId=b23510-82279647-13fa-4930-8338-ec85988b6bed

Response

<BulkJobSummaryResponse>

<RequestId>71d7261e-bbf7-487d-b201-6d3557370cd2</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

<BulkJobSummary>

<BulkJobRequestId>b23510-82279647-13fa-4930-8338-ec85988b6bed</BulkJobRequestId>

<CorrelationId>My Job Id</CorrelationId>

<Messages>1000000</Messages>

<Clicks>123231</Clicks>

<Opens>152323</Opens>

<Bounces>1283</Bounces>

<Unsubsribes>0</Unsubsribes>

<Deliveries>998121</Deliveries>

<SpamComplaints>2</SpamComplaints>

<RenderErrors>0</RenderErrors>

</BulkJobSummary>

</BulkJobSummaryResponse>

Java SDK

Click here for more information on using the MessageGears Java SDK

package com.messagegears.sdk.examples;

import com.messagegears.sdk.v3_1.BulkJobSummaryResponse;

import com.messagegears.sdk.MessageGearsClient;

import com.messagegears.sdk.MessageGearsProperties;

import com.messagegears.sdk.model.request.BulkJobSummaryRequest;

import com.messagegears.sdk.output.ScreenWriter;

public class BulkJobSummaryExample {

public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static final String MY_BULK_JOB_REQUEST_ID = "place your bulk job request id here";

public static void main(String[] args) {

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);

props.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

// Create the MessageGears client object

MessageGearsClient client = new MessageGearsClient(props);

// Invoke the BulkJobSummary API

BulkJobSummaryRequest request = new BulkJobSummaryRequest();

request.setRequestId(MY_BULK_JOB_REQUEST_ID);

BulkJobSummaryResponse response = client.bulkJobSummary(request);

// Print the result

ScreenWriter.printResponse(response);

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;

using System.IO;

using MessageGears;

using MessageGears.Model;

using MessageGears.Model.Generated;

namespace MessageGears.Examples

{

public class BulkJobSummaryExample

{

public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public const String MY_BULK_JOB_REQUEST_ID = "place your bulk job request id here";

public static void Main ()

{

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;

props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

// Create the MessageGears client object

MessageGearsClient client = new MessageGearsClient(props);

// Invoke the BulkJobSummary API

BulkJobSummaryResponse response = client.BulkJobSummary(MY_BULK_JOB_REQUEST_ID);

// Print the result

client.PrintResponse(response);

}

}

}

BulkCampaignSubmit is used to send a email message to a list of one or more recipients. There is no hard limit on the size of the list and millions of emails can be sent from a single invocation of this API. To use this API, you must create an XML file that contains a list of all the recipients and place it on an HTTP server where it can be retrieved by the MessageGears system. Then you make an API call and supply the URL where the recipient file is located along with the CampaignId of a promoted campaign. MessageGears will then retrieve the recipient file and perform a "mail merge" with the promoted Campaign content to generate the individual email messages.

Deprecated Versions

(none)

Required Parameters

Parameter

Personalizable

Description

Action

BulkCampaignSubmit

AccountId

The MessageGears account id to which this item belongs.

ApiKey

A secret key only known by you. Keep this key confidential.

CampaignId

The CampaignId of the campaign to be used to render the message. This Id is displayed when creating and promoting a campaign.

RecipientListXmlUrl

A URL pointing to a file that contains a list of recipient data. The file may be compressed using the "ZIP" or "GZIP" algorithms. Supported protocols are http, https, and Amazon S3 . The referenced file must have a ".xml" extension if uncompressed, ".zip" if compressed using ZIP, and ".gz" if compressed using Gzip.

Click here for more information.

Optional Parameters

Parameter

Personalizable

Description

ContextDataXml

This field is used to supply data to the template that is not directly related to the recipient. For example, this field could contain data about weekly airfare specials by city. The template could then select only the fares that originated from the same city as the recipients home. This helps make it easy to create templates with relevant data for each recipient.

Click here for more information.

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.

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.

Programming Examples

REST

Java SDK

C# SDK

REST

Request

https://api.messagegears.net/3.1/WebService

?Action=BulkCampaignSubmit

&AccountId=123456789

&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd

&CampaignId=22222222

&RecipientListXmlUrl=http://www.mycompany.com/file/WelcomeRecipients.xml

Response

<BulkJobSubmitResponse>

<RequestId>b23510-82279647-13fa-4930-8338-ec85988b6bed</RequestId>

<Result>REQUEST_SUCCESSFUL</Result>

</BulkJobSubmitResponse>

Java SDK

Click here for more information on using the MessageGears Java SDK

package com.messagegears.examples;

import com.messagegears.sdk.MessageGearsClient;

import com.messagegears.sdk.MessageGearsProperties;

import com.messagegears.sdk.model.request.BulkCampaignSubmitRequest;

import com.messagegears.sdk.output.ScreenWriter;

import com.messagegears.sdk.v3_1.BulkJobSubmitResponse;

public class BulkCampaignSubmit {

public static final String MY_EMAIL_ADDRESS = "place your email address here";

public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void main(String[] args) {

// Create the properties object containing the necessary properties

MessageGearsProperties properties = new MessageGearsProperties();

properties.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);

properties.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

// Create the main client object

MessageGearsClient client = new MessageGearsClient(properties);

// Create a bulk campaign request

BulkCampaignSubmitRequest request = new BulkCampaignSubmitRequest();

// Set the URL where the recipient XML file can be retrieved

request.setRecipientListXmlUrl("http://www.mycompany.com/recipient.xml");

// Set the campaign id

request.setCampaignId(12345);

// Execute the request

BulkJobSubmitResponse response = client.bulkCampaignSubmit(request);

// Print the result (success or failure)

ScreenWriter.printResponse(response);

}

}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;

using MessageGears;

using MessageGears.Model;

using MessageGears.Model.Generated;

namespace MessageGears.Sample

{

public class BulkCampaignSample

{

// Replace this value with your email address

public const String MY_EMAIL_ADDRESS = "place your email address here";

public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";

public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";

public static void Main ()

{

// Create the properties object containing the necessary properties

MessageGearsProperties props = new MessageGearsProperties();

props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;

props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

// Create the main client object

MessageGearsClient client = new MessageGearsClient(props);

// Create a bulk campaign request

BulkCampaignSubmitRequest request = new BulkCampaignSubmitRequest();

// Set the URL where the recipient XML file can be retrieved

request.RecipientListXmlUrl = "http://www.mycompany.com/recipient.xml";

// Set the campaign id

request.CampaignId = "12345";

// Execute the request

BulkJobSubmitResponse response = client.BulkCampaignSubmit(request);

// Print the result (success or failure)

client.PrintResponse(response);

}

}

}

Context Data is part of an advanced feature specific to bulk jobs. By using this feature, you are able to place any XML data of your choosing into the "context" of the content rendering process. This allows you to access the data inside the template in the same way you access data about the email recipient. Context Data offers even more powerful personalization by giving the template author a place to store and reference data that can be used for cross-selling, weekly specials, and other data that can be presented to each recipient based on attributes associated with that particular recipient.

Recipient XML

<RecipientList>

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

<FirstName>Joe</FirstName>

<HomeCity>ATL</HomeCity>

</Recipient>

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

<FirstName>Jane</FirstName>

<HomeCity>DFW</HomeCity>

</Recipient>

</Recipient>

Context XML

<Specials>

<Special>

<DepartureCity>ATL</DepartureCity>

<DestinationCity>HNL</DestinationCity>

<Fare>625.00</Fare>

</Special>

<Special>

<DepartureCity>ATL</DepartureCity>

<DestinationCity>SFO</DestinationCity>

<Fare>375.50</Fare>

</Special>

<Special>

<DepartureCity>DFW</DepartureCity>

<DestinationCity>HNL</DestinationCity>

<Fare>550.25</Fare>

</Special>

<Special>

<DepartureCity>DFW</DepartureCity>

<DestinationCity>SFO</DestinationCity>

<Fare>225.00</Fare>

</Special>

</Specials>

HTML Template

Hello ${Recipient.FirstName},

Here are the fare specials you asked to be alerted about:

<#list Specials.Special as special>

<#if special.DepartureCity == recipient.HomeCity>

Destination: ${special.DestinationCity} Fare: ${special.Fare}

</#if>

</#list>

Results

Hello Joe,

Here are the fare specials you asked to be alerted about:

Destination: HNL Fare: 625.00

Destination: SFO Fare: 375.50

Hello Jane,

Here are the fare specials you asked to be alerted about:

Destination: HNL Fare: 550.25

Destination: SFO Fare: 225.00

For bulk jobs, you must pass in the recipient data as a URL pointing to a file which MessageGears retrieve. Currently, the supported protocols are http, https, and Amazon S3. The file may be of any name and may also be plain text or compressed. Passing a file in this way allows for a virtually unlimited number of recipients. We recommend that the file be encoded using the UTF8 (or a compatible subset) character encoding.

Supported File Formats

Uncompressed If the file is not compressed, it must have a ".xml" extension

Zip If the file is compressed using ZIP, it must have a ".zip" file extension. The "zipped" file must contain only 1 file and it should not contain any path information (it should unzip into the same directory in which the unzip command is executed)

GZip If using Gzip, the file must have a ".gz" extension

Compressing the file will reduce the your bandwidth requirements by as much as 95\% or more and allows the job to be processed much more quickly.

Example URLs

http://www.mycomapny.com/files/recipient.xml

https://username:[email protected]/files/recipient.gz

s3://mycompany-bucket/recipient.zip

Click here for more details on referencing remote files

File Contents

The contents of the file be a well-formed XML document. The RecipientList element must be the root element, and must contain only Recipient elements as children. Each Recipient element must contain an EmailAddress element and may contain a RecipientId element which has special meaning to the system. An example of the recipient XML is show below.

<RecipientList>

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

</Recipient>

<Recipient>

<EmailAddress>[email protected]</EmailAddress>

</Recipient>

</RecipientList>

Click here for more details regarding the use of the Recipient element

You may add as many as 5 custom header to your email messages. All headers must begin with "X-" or your API request will be rejected.

Customer headers can be useful for inserting data into your messages that may help you with customer support, seedlist testing, etc. Supplying custom headers in your API calls is easy, and works in a very similar manner as the attachment parameters.

The example below shows you how you would add 2 headers in a Transactional job. Pass in the following 4 parameters in the API call:

HeaderName.1=X-CampaignId

HeaderValue.1=12345

HeaderName.2=X-RecipientId

HeaderValue.2=2897423894

In the resulting email you would see the following headers in your message source:

X-CampaignId: 12345

X-RecipientId: 2897423894

You can set this value to "true" in your Bulk and Transactional API calls and it will cause a "List-Unsubscribe" header to be added to your email message(s).

This header has special meaning to several ISPs and Email Readers (most notably Gmail). If present, it provides the information needed to unsubscribe an email address from receiving future mailings.

Example Unsubscribe Header

List-Unsubscribe: <http:>,

<mailto:unsub-2.23295228.23295228.t411-ef564854-2ccb-4b5f-8a35-307118b68b7bqna.ebl=pbz=zrffntrtrnef@gears1.messagegears.net>

Some ISPs will send an email message to the "mailto" address in the header. Others will invoke the url in the "http" section of the header. In either event, you will receive an "unsubscribe" activity in your daily or real-time data feed.

Gmail's Use of the Unsubscribe Header

When using this feature, always be sure to test it with a few small jobs first. Improper configuration may cause tracking to be disabled, and broken links for your customers.

We've done our best to make these urls safe and friendly, but some of your email recipients may be hesitant to click on a URL in you message that is not from your domain. You can supply a parameter called "CustomTrackingDomain" and provide the string to use as the first part of the URL used in click, open, unsubscribe, and microsite links that might be present in your email message. When we generate the link, we will use the string you supplied to build the url.

Default Tracking URLs

http://www.messagegears.net/c/1/?aId=23295228&requestId=t311

http://www.messagegears.net/o/1/23295228

Same URLs Using a Custom Tracking Domain

http://email.mycompany.com/c/1/?aId=23295228&requestId=t311

http://email.mycompany.com/o/1/23295228

Changes to your DNS Settings

To make this work you’ll need to have a network administrator at your company make a change to your Domain Name Server (DNS). Once you’ve decided on the domain name to use, you’ll need to create a CNAME record in your DNS service.

Name

Type

Value

email.mycompany.com.

CNAME

www.messagegears.net.