Skip to main content

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:

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​

ParameterPersonalizableDescription
ActionTransactionalCampaignSubmit
AccountIdThe MessageGears account id to which this item belongs.
ApiKeyA secret key only known by you. Keep this key confidential.
CampaignIdThe CampaignId of the campaign to be used to render the message. This Id is displayed when creating and promoting a campaign.
RecipientXmlThe XML for a single recipient supplied in the prescribed format. Click here for more information.
RecipientTokenThe recipient token provided by MessageGears for the content to be forwarded.

Optional Parameters​

ParameterPersonalizableDescription
CorrelationIdThis 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>john.doe@messagegears.com</EmailAddress></Recipient>  
&RecipientToken=specifiedrecipienttoken

Response

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