ForwardToAFriend v3.1

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:

1
http://mywebpage.com/forwardtoafriend.html?recipientToken=${Gears.recipientToken()}
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:

1
2
3
4
5
6
7
8
<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>
<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:

1
2
3
4
5
6
7
8
9
10
11
<html>
<body>
  Hello ${Recipient.FirstName},
 
  Here's the original message!
  
  <hr>
  <#assign originalContent = OriginalMessage.Html?interpret>
  <@originalContent />
</body>
</html>
<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.

Prior 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

Request

https://api.messagegears.net/3.1/WebService
?Action=ForwardToAFriend
&AccountId=123456789
&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd
&CampaignId=22222222
&RecipientXml=<Recipient><EmailAddress>john.doe@messagegears.com</EmailAddress></Recipient>
&RecipientToken=specifiedrecipienttoken

Response

<ForwardToAFriendResponse>
    <RequestId>o23110-a9e77b7c-c980-4ff5-8ede-546fbe0bad66</RequestId>
    <Result>REQUEST_SUCCESSFUL</Result>
</ForwardToAFriendResponse>