Method 1: Use the delivery API (Preferred)
The delivery API is a POST request that works with build-time email. This option is the preferred method for build-time email.
Most email clients do not allow POST requests. Therefore, this API is not recommended for open-time use cases. Some email clients, such as Gmail or Outlook, can cache the content or block the image and require the recipient to pro-actively allow the image to render.
You cannot return default content using the delivery API.
The following code is a sample API delivery request:
curl -X POST \
'https://clientcode.tt.omtrdc.net/rest/v1/mbox/?client=clientcode' \
-H 'authorization: Bearer 3423614b-4843-4664-83c4-c6c3f6c8869b' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"mbox" : "email-mbox",
"tntId" : "111499796294071-449025.28_44",
"requestLocation" : {
"host" : "prod"
},
"profileParameters" : {
},
"mboxParameters" : {
"at_property": "b468a242-64a4-32a0-ca0c-890bddd78789",
"entity.id": "article-123",
"entity.event.detailsOnly" : "true"
}
"contentAsJson": true
}'
Where clientcode
is your Target client code.
sessionId
and one of tntId
or thirdPartyId
for each email recipient (for example, for each API call). If you do not provide unique values for these fields, API response can slow or fail due to many events generated within a single profile.See Delivery API documentation for more information.
Method 2: Use a rawbox email template
A rawbox is similar to an mbox request, but for non-Web environments, such as email service providers (ESPs). Because you don’t have the Adobe Experience Platform Web SDK or at.js to use in rawbox requests, you must create your requests manually. The examples below explain how to work with rawbox requests in email.
This approach allows you to track performance of recommendations in emails, test them in the normal way with a recommendation, and continue tracking on the site.
Set up a Recommendations activity in Target, using the Form-Based Experience Composer option. For the location, select the name of the mbox you’ve chosen to use in the rawbox request coming from the ESP. Select a design with the look and feel you want for your email. At email build time, the ESP makes a call to the Target servers for each rawbox in each email being generated. Your ESP must have a way to include the returned HTML in the email when it is sent.
The email system you use must be able to handle the following scenarios:
A valid response is received, but no recommendations are present
- In this case, the response is whatever is set as the
mboxDefault
parameter value. See explanation below on this parameter. - The email provider should have a default HTML block of recommendations to use in this case.
The Target server times out and returns without data
-
In this case, the Target server returns the following content:
//ERROR: application server timeout
-
The email application should search for that text and must be able to handle the error. The email provider has multiple options for handling this case:
- Try another server call immediately (recommended, perhaps with an attempt counter).
- Toss out that particular email and continue to the next one.
- Queue that particular email and rerun failed emails as a batch at the end of the initial run.
Sample request URL
https://client_code.tt.omtrdc.net/m2/client_code/ubox/raw?mbox=mbox_name&mboxSession=1396032094853-955654&mboxPC=1396032094853-955654&mboxXDomain=disabled&entity.event.detailsOnly=true&mboxDefault=nocontent&mboxNoRedirect=1&entity.id=2A229&entity.categoryId=5674
Required parameters:
entity.id
or entity.categoryId
or both, depending on the type of recommendation criteria. The sample call above includes both.Parameter | Value | Description | Validation |
---|---|---|---|
client_code | client_code | The client’s code used in Recommendations. Your Adobe consultant can provide this value. | |
mbox | mboxName | The mbox name that is used for targeting. | Same validation as for all mbox calls. 250 character limit. Cannot contain any of the following characters: ', ", %22, %27, <, >, %3C, %3E |
mboxXDomain | disabled | Prevents the response from setting a cookie in non-web environments. | |
entity.id (Required for certain types of criteria: view/view, view/bought, bought/bought) | entity_id | The productId the recommendation is based on, such as an abandoned product in the cart, or a previous purchase. If required by the criteria, the rawbox call must include the entity.id . | |
entity.event.detailsOnly | true | If entity.id is passed, it is highly recommended to also pass this parameter to prevent the request from incrementing the number of tallied page views for an item, so as not to skew product view-based algorithms. | |
entity.categoryId (Required for certain types of criteria: most viewed by category and top sellers by category) | category_id | The category the recommendation is based on, such as top sellers in a category. If required by the criteria, the rawbox call must include the entity.categoryId . | |
mboxDefault | https://www.default.com | If the mboxNoRedirect parameter is not present, mboxDefault should be an absolute URL that returns default content if no recommendation is available. This URL can be an image or other static content.If the mboxNoRedirect parameter is present, mboxDefault can be any text indicating there are no recommendations, for example no_content .The email provider must handle the case where this value is returned and insert default HTML into the email. Security best practice: If the domain used in the mboxDefault URL is not allowlisted, you can be exposed to a risk of an Open Redirect Vulnerability. To avoid the unauthorized use of Redirector links or mboxDefault by third parties, Adobe recommends you use “authorized hosts” to allowlist the default redirect URL domains. Target uses hosts to allowlist domains to which you want to allow redirects. For more information, see Create Allowlists that specify hosts that are authorized to send mbox calls to Target in Hosts. | |
mboxHost | mbox_host | The domain that is added to the default environment (host group) when the call fires. | |
mboxPC | Empty | (Required for recommendations that use a visitor’s profile.) If no “thirdPartyId” was provided, a new tntId is generated and returned as part of the response. Otherwise remains empty. Note: Be sure to provide a unique value of mboxSession and mboxPC for each email recipient (i.e., for each API call). If you do not provide unique values for these fields, API response can slow or fail due to the large number of events generated within a single profile. | 1 < Length < 128 Cannot contain more than a single “.” (dot). The only dot allowed is for profile location suffix. |
Optional parameters
Parameter | Value | Description | Validation |
---|---|---|---|
mboxPC (Optional) | mboxPCId | Target visitor ID. Use this value when if you want to track a user full-circle back to your site across multiple visits, or when using a user profile parameter. This value must be the actual Adobe Target PCID for the user, which would be exported from the website to your CRM. The email provider would retrieve this ID from your CRM or Data Warehouse, and use it for the value of this parameter. The mboxPC value is also useful for tracking visitor site behavior across multiple visits for metrics tracking when a recommendation is part of an A/B activity.Note: Be sure to provide a unique value of mboxSession and mboxPC for each email recipient (i.e., for each API call). If you do not provide unique values for these fields, API response can slow or fail due to the large number of events generated within a single profile. | 1 < Length < 128 Cannot contain more than a single “.” (dot). The only dot allowed is for profile location suffix. |
mboxNoRedirect (Optional) | 1 | By default, the caller is redirected when no deliverable content is found. Use to disable the default behavior. | |
mbox3rdPartyId | xxx | Use this option if you have your own custom visitor ID to use for profile targeting. |
Potential Target server responses
Response | Description |
---|---|
//ERROR: | Generated by load balancer when it can’t return content |
Success | The mboxNoRedirect parameter is set to ‘true’ and the server does not return any recommendations (i.e., there is no match for the mbox or the server cache is not initialized). |
bad request |
The
|
Cannot redirect to default content, please specify mboxDefault parameter | mboxDefault not specified when no match for the request exists and mboxNoRedirect parameter is not specified. |
Invalid mbox name:= MBOX_NAME | Indicates mbox parameter contains invalid characters. |
Mbox name [MBOX_NAME] is too long | Indicates mbox parameter is longer than 250 characters. |
Method 3: Use the Recommendations Download API
Set up a recommendation as usual, but choose download only in the presentation section instead of a template and mbox combination. Then in the ESP, tell the ESP what recommendation ID you created. The ESP accesses the recommendation data via API. This data shows which items should be recommended for a particular category or key item, such as items in an abandoned cart. The ESP stores this data, connects it with their own look and feel, displays information about each item, and delivers that in the emails.
With this option, the recommendations server cannot directly track the performance of a recommendation or split traffic across multiple algorithm/template combinations. Also, the recommendations are not tied to a visitor profile.
For more information about the download API, see Legacy APIs > Download.
Adobe Target Maturity Webinar Series
Adobe Customer Success Webinars
Tuesday, Feb 4, 4:00 PM UTC
Adobe Target innovations, including GenAI, and best practices on AI-powered personalization and experimentation at scale.
Register