MessagePreview v3.1

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.

Prior Versions

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.

Click here for more information regarding dynamic email content.
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

Request

https://api.messagegears.net/3.1/WebService
?Action=MessagePreview
&AccountId=123456789
&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd
&FromName=Customer Support
&FromAddress=customer.support@mycompany.com
&SubjectLine=Message to ${Recipient.FirstName}
&HtmlTemplate=<html>Hello, ${Recipient.FirstName}!</html>
&RecipientXml=<Recipient><EmailAddress>john.doe@aol.com</EmailAddress><FirstName>John</FirstName></Recipient>

Success Response

<MessagePreviewResponse>
    <RequestId>m311-6cc4d321-fbce-4e86-aa53-c50766f03eaa</RequestId>
    <Result>REQUEST_SUCCESSFUL</Result>
    <PreviewContent>
        <FromAddress>customer.support@mycompany.com</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>customer.support@mycompany.com</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>

Click here to see more details about using the MessageGears Java SDK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
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("messagepreview@messagegears.net");
        request.setFromName("MessageGears Preview");
        request.setHtmlTemplate(getHtmlTemplate());
        request.setRecipientXml(getRecipientXml());
        request.setOnBehalfOfAddress("preview@messagegears.com");
        request.setOnBehalfOfName("MessageGears");
        request.setReplyToAddress("no-reply@messagegears.com");
        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>nosuchuser@blackhole.messagegears.com</EmailAddress>" +
            "<RecipientId>recipient123</RecipientId></Recipient>";
    }
}
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("messagepreview@messagegears.net");
        request.setFromName("MessageGears Preview");
        request.setHtmlTemplate(getHtmlTemplate());
        request.setRecipientXml(getRecipientXml());
        request.setOnBehalfOfAddress("preview@messagegears.com");
        request.setOnBehalfOfName("MessageGears");
        request.setReplyToAddress("no-reply@messagegears.com");
        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>nosuchuser@blackhole.messagegears.com</EmailAddress>" +
            "<RecipientId>recipient123</RecipientId></Recipient>";
    }
}

Click here to see more details about using the MessageGears .Net SDK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
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 = "messagepreview@messagegears.net";
            request.FromName = "MessageGears Preview";
            request.HtmlTemplate = getHtmlTemplate();
            request.RecipientXml = getRecipientXml();
            request.OnBehalfOfAddress = "preview@messagegears.com";
            request.OnBehalfOfName = "MessageGears";
            request.ReplyToAddress = "no-reply@messagegears.com";
            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>nosuchuser@blackhole.messagegears.com</EmailAddress>" +
                                "<RecipientId>You</RecipientId></Recipient> ";
        }
    }
}
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 = "messagepreview@messagegears.net";
			request.FromName = "MessageGears Preview";
			request.HtmlTemplate = getHtmlTemplate();
			request.RecipientXml = getRecipientXml();
			request.OnBehalfOfAddress = "preview@messagegears.com";
			request.OnBehalfOfName = "MessageGears";
			request.ReplyToAddress = "no-reply@messagegears.com";
			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>nosuchuser@blackhole.messagegears.com</EmailAddress>" +
                                "<RecipientId>You</RecipientId></Recipient> ";
		}
 	}
}