MessagePreview v3.1

Sam

Updated September 02, 2024 14:14

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

REST

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>

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("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>";
 }
}

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 = "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> ";
 }
 }
}