Prerequisite
For detailed information on the Email Recommendations feature and its use-cases, go through its feature guide.
What are Email Recommendations APIs?
The Email Recommendations APIs are same as the Recommendations and Pathways API v2, for all the 5 widget types, except that each API can now be either a Proxy API or an Image API.
The response formats of the Email Recommendations APIs are different from the Recommendations APIs. Unlike the latter, where we get a JSON response containing details of multiple products in that widget, the Email Recommendations APIs' response is a redirect (HTTP 302) to either a Product Description Page or an Image of a single product.
Proxy and Image APIs
The Proxy APIs redirect to the Product Description Page of the product and Image APIs redirect to the Image of the product.
The email should have a template defined, which can then be integrated with different Email Service Providers.
Here is a sample email template:
<html>
<body>
<h2> Sale going on!!! </h2>
<a href="http://pathways-email.dxpapi.com/api/v2/widgets/proxy/category/kjy4y2jv?_br_uid_2=uid%3D1251839531436%3Av%3D15.0%3Ats%3D1606749087372%3Ahc%3D13&account_id=6370&domain_key=pacific_supply&user_id=6453546d-5b17-41f4-8fad-43f379d3657f&url=https%3A%2F%2Fwww.pacific.com%2Fso3005719.html&ref_url=https%3A%2F%2Fwww.pacific.com%2Fl%2F%3Fsearchinfo%3Dps5%2520console%26mode%3Dedu%26sel%3DItem-Condition_New-Items&fields=pid&cat_id=na_280200000000&query=box&start=0&rows=5">
<img src="http://pathways-email.dxpapi.com/api/v2/widgets/image/category/kjy4y2jv?_br_uid_2=uid%3D1251839531436%3Av%3D15.0%3Ats%3D1606749087372%3Ahc%3D13&account_id=6370&domain_key=pacific_supply&user_id=6453546d-5b17-41f4-8fad-43f379d3657f&url=https%3A%2F%2Fwww.pacific.com%2Fso3005719.html&ref_url=https%3A%2F%2Fwww.pacific.com%2Fl%2F%3Fsearchinfo%3Dps5%2520console%26mode%3Dedu%26sel%3DItem-Condition_New-Items&fields=pid&cat_id=na_280200000000&query=box&start=0&rows=5" width="200" height="300"/>
</a>
<a href="http://pathways-email.dxpapi.com/api/v2/widgets/proxy/category/kjy4y2jv?_br_uid_2=uid%3D1251839531436%3Av%3D15.0%3Ats%3D1606749087372%3Ahc%3D13&account_id=6370&domain_key=pacific_supply&user_id=6453546d-5b17-41f4-8fad-43f379d3657f&url=https%3A%2F%2Fwww.pacific.com%2Fso3005719.html&ref_url=https%3A%2F%2Fwww.pacific.com%2Fl%2F%3Fsearchinfo%3Dps5%2520console%26mode%3Dedu%26sel%3DItem-Condition_New-Items&fields=pid&cat_id=na_280200000000&query=box&start=1&rows=5">
<img src="http://pathways-email.dxpapi.com/api/v2/widgets/image/category/kjy4y2jv?_br_uid_2=uid%3D1251839531436%3Av%3D15.0%3Ats%3D1606749087372%3Ahc%3D13&account_id=6370&domain_key=pacific_supply&user_id=6453546d-5b17-41f4-8fad-43f379d3657f&url=https%3A%2F%2Fwww.pacific.com%2Fso3005719.html&ref_url=https%3A%2F%2Fwww.pacific.com%2Fl%2F%3Fsearchinfo%3Dps5%2520console%26mode%3Dedu%26sel%3DItem-Condition_New-Items&fields=pid&cat_id=na_280200000000&query=box&start=1&rows=5"width="200" height="300"/>
</a>
<a href="http://pathways-email.dxpapi.com/api/v2/widgets/proxy/category/kjy4y2jv?_br_uid_2=uid%3D1251839531436%3Av%3D15.0%3Ats%3D1606749087372%3Ahc%3D13&account_id=6370&domain_key=pacific_supply&user_id=6453546d-5b17-41f4-8fad-43f379d3657f&url=https%3A%2F%2Fwww.pacific.com%2Fso3005719.html&ref_url=https%3A%2F%2Fwww.pacific.com%2Fl%2F%3Fsearchinfo%3Dps5%2520console%26mode%3Dedu%26sel%3DItem-Condition_New-Items&fields=pid&cat_id=na_280200000000&query=box&start=2&rows=5">
<img src="http://pathways-email.dxpapi.com/api/v2/widgets/image/category/kjy4y2jv?_br_uid_2=uid%3D1251839531436%3Av%3D15.0%3Ats%3D1606749087372%3Ahc%3D13&account_id=6370&domain_key=pacific_supply&user_id=6453546d-5b17-41f4-8fad-43f379d3657f&url=https%3A%2F%2Fwww.pacific.com%2Fso3005719.html&ref_url=https%3A%2F%2Fwww.pacific.com%2Fl%2F%3Fsearchinfo%3Dps5%2520console%26mode%3Dedu%26sel%3DItem-Condition_New-Items&fields=pid&cat_id=na_280200000000&query=box&start=2&rows=5"width="200" height="300"/>
</a>
</body>
</html>
In this template, we first decide the number of desired image slots, let's say, 3. For each slot, we have to define a hyperlink HTML tag (<a>) and an image HTML tag (<img>). The hyperlink tag will point to the Proxy API call and Image tag will point to the Image API call defined above.
For each image slot, the API calls are the same, except that we update the start parameter. start=0 denotes the first product of the recall set, start=1 denotes the second product of the recall set, and so on.
Filtering support
Email Recommendations APIs (both Proxy and Image) support the filtering capabilities of Recommendations and Pathways APIs.
Sending additional parameters to track email campaigns
Email Recommendations Proxy APIs allow you to track email campaigns by passing additional parameters. You must follow the below guidelines to pass such parameters:
-
The additional parameters must start with the prefix
brtrk_. We will ignore the parameters with an incorrect prefix. For instance, the parameter isutm_campaign=special_holiday; with the prefix, it becomesbrtrk_utm_campaign=special_holiday. -
You can pass up to 10 additional parameters. If more than 10
brtrk_prefixed parameters are passed, we ignore them. -
Parameter names and values must be alphanumeric. The only special characters supported are underscore (_) and hyphen (-). If any other characters are passed, we will ignore the parameter.
-
Each parameter name and value can be a maximum of 100 characters. If they exceed this limit, we will ignore them.
-
You don’t need to implement any mechanism to remove prefixes from parameters. Our system identifies additional parameters and removes the prefix. Refer to the sample request and response.
https://pathways-email.dxpapi.com/api/v2/widgets/proxy/global/nj3806w9?
account_id=6092
&domain_key=homeoasis
&_br_uid_2=uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55
&url=https%3A%2F%2Fwww.homeoasis.com%2F
&view_id=hs
&query=box
&rows=9
&start=0
&brtrk_utm_medium=AAA #additional parameter
&brtrk_utm_source=BBB #additional parameter
&brtrk_utm_campaign=CCC #additional parameter
&brtrk_utm_term=DDD #additional parameter
&brtrk_utm_content=EEE #additional parameter
https://www.homeoasis.com/womens/necklaces/pendant-necklace-in-sterling-silver-with-diamond-p-1234567.html?
utm_medium=AAA
&utm_source=BBB
&utm_campaign=CCC
&utm_term=DDD
&utm_content=EEE
Run in Postman
Easily import the Discovery API collection and try the endpoints in Postman. It offers many examples of how the endpoints can be used for different use cases.
Follow this quick step-by-step guide to set up the environment and use the APIs: Postman Collections Welcome Kit
OpenAPI spec
The detailed OpenAPI specification for the Email recommendations widget APIs v2 can be found on GitHub:
Endpoints
Production:
Proxy API: https://pathways-email.dxpapi.com/api/v2/widgets/proxy/{widget type}/{widget_id}
Image API: https://pathways-email.dxpapi.com/api/v2/widgets/image/{widget type}/{widget_id}
Staging:
Proxy API: https://pathways-email-staging.dxpapi.com/api/v2/widgets/proxy/{widget type}/{widget_id}
Image API: https://pathways-email-staging.dxpapi.com/api/v2/widgets/image/{widget type}/{widget_id}