Articles in this section

Advanced Personalization Through 1-to-1 APIs

Contextual Data API Overview

MessageGears offers a powerful set of APIs designed to allow additional data elements to be gathered via individual API calls prior to the message personalization process. This can include collecting data from your MessageGears datasets, internal API services, or external partner APIs. Multiple calls to services may be made, allowing data to be collected from several different API services before the message rendering process occurs. This functionality is available for both large Marketing sends launched by Accelerator and individual transactional sends triggered via API calls. 


Transactional Message Example

A common use case for our 1-to-1 Context API functionality is appending additional data to an event driven API message, like applying additional personalization to a Purchase Confirmation message.


In many implementations, the API trigger for a Purchase Confirmation message is powered by the internal web team, which often has access to information like the user's Email, First & Last Name, Mailing Address, and product and pricing information for the items purchased. Often, however, additional information may be needed to perform additional personalization, like a need to identify loyalty status, rewards options, and related product recommendations and details for the items purchased.




Our 1-to-1 API functionality allows API calls to internal services to collect this additional information for each recipient in situations where it may not be available to the service making the initial request. Multiple calls to internal services may be made to collect other information needed to personalize the message, which can then be leveraged during the message rendering process.


Third-party Integration Example

In some cases, clients are interested in leveraging third party partners to provide offer management, recommendations, or content optimization functionality. For partners who provide real-time access to these services, our 1-to-1 APIs allow clients to pass in information about the recipient and message context, in able to deliver real-time personalized experiences within Email, Push, and SMS content.




This integration also allows for on-going experimentation through third-party partners like Phrasee, where content optimization can be applied to on-going triggered and transactional sends over extended periods of time.


Customer Profile Append Example

Another popular use case involves leveraging Customer Profile Data managed through Context Data sources. This allows data from multiple different databases to be combined into a highly scalable, highly available cached dataset that can be included in your transactional and marketing campaigns. Up to 30 queries can be performed against these datasets within a single message to surface additional data points required for message personalization context at render time.

Data within Context Datasets are constantly monitored for changes to ensure each message has access to the most up-to-date data available at render time (or at interaction time, when using partners like Movable Ink). 



Context Datasets can be used to provide access to Customer Data, Offer Data, or other important datasets during the message rendering process within MessageGears for Email, Push, SMS, and other experiences, or access can be provided to external partners like Movable Ink, Phrasee, and many others, to provide consistent customer experiences and simplify integration between systems.


1-to-1 API Setup

Data calls are made from the MessageGears Cloud platform for scalability and high-availability during the message rendering and personalization process. API setup is performed within Accelerator and details regarding what data is needed for each piece of content and campaign are passed through to our cloud platform during the campaign launch process to collect necessary data during the rendering process.

In order to setup setup a new 1-to-1 datasource, you need the following information:

  • URL Endpoint of the API
  • Request Type of the API
    • GET, PUT, POST, and PATCH calls are supported
  • Authentication Credentials
  • Request Parameters
    • Request Parameters may be included on the URL or as a set of personalizable parameters
The parameters will have full access to the Recipient Data for each recipient, 
allowing items like RecipientId, EmailAddress, Campaign Information,
and other fields to be passed into the API call to provide context for the request.



Once the above information has been collected and entered into the UI, you can easily perform test calls to verify the implementation and view the sample payload results. Any well-formed JSON or XML is accepted and provided to the rendering context for personalization of the message. The data returned may include complex, nested information as long as the total result size is less than 5MB of data, and may include content such as HTML, FreeMarker, or other embedded data which can be included and referenced within the resulting message personalization.


Example UI Setup




  1. A maximum of 5 total API endpoints may be leveraged within a single template
  2. Resulting data must be less than 5MB in total
  3. Configurable API timeouts are defaulted to 100ms
  4. Resulting data must be well-formed JSON or XML only
  5. Special characters must be appropriately escaped within the resulting data format
  6. When referencing Datasets, a maximum of 30 individual lookups can be performed for a single API call


Once setup, 1-to-1 APIs can be leveraged within any Email, SMS, or Mobile Push Template by selecting the appropriate API datasets within the Mapped Data Sources section of the template. A maximum of 5 sources may be used within any template. Once linked to the template, you can reference the resulting data directly in the template as if it was a part of the Recipient or Contextual Data. 


Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.