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.

NOTE
Be sure to provide a unique value for both 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.

NOTE
When using a rawbox and Target, see the important security notice under Create allowlists that specify hosts that are authorized to send mbox calls to Target.

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:

NOTE
To use Recommendations in email, the rawbox call must usually include either the entity.id or entity.categoryId or both, depending on the type of recommendation criteria. The sample call above includes both.
ParameterValueDescriptionValidation
client_codeclient_codeThe client’s code used in Recommendations. Your Adobe consultant can provide this value.
mboxmboxNameThe 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
mboxXDomaindisabledPrevents 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_idThe 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.detailsOnlytrueIf 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_idThe 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.
mboxDefaulthttps://www.default.comIf 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.
mboxHostmbox_hostThe domain that is added to the default environment (host group) when the call fires.
mboxPCEmpty(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

ParameterValueDescriptionValidation
mboxPC
(Optional)
mboxPCIdTarget 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)
1By default, the caller is redirected when no deliverable content is found. Use to disable the default behavior.
mbox3rdPartyIdxxxUse this option if you have your own custom visitor ID to use for profile targeting.

Potential Target server responses

ResponseDescription
//ERROR:Generated by load balancer when it can’t return content
SuccessThe 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 mbox parameter is missing.

  • Either mboxDefault or the mboxNoRedirect parameter is not specified.
  • mboxTrace request parameter is specified but mboxNoRedirect is not.
  • mboxTargetparameter is not specified when mbox names end with -clicked suffix.
Cannot redirect to default content, please specify mboxDefault parametermboxDefault not specified when no match for the request exists and mboxNoRedirect parameter is not specified.
Invalid mbox name:= MBOX_NAMEIndicates mbox parameter contains invalid characters.
Mbox name [MBOX_NAME] is too longIndicates 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.

Target


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