NAV Navbar
Logo

Legacy /v1/mbox and /v2/batchmbox API

This API documentation outlines the legacy /v1/mbox and /v2/batchmbox API. It is highly recommended that customers use the new /v1/delivery API.

Server Side Delivery

The Server Side Delivery API is designed to deliver experiences with any server side platform or an application that can make HTTP/s calls. This is valuable for organizations that want to deliver targeting to a non-browser based IoT device, such as a connected TV, kiosk, or in-store digital screen.

Getting Started

Deliver your Target experiments & personalizations using the Delivery API with three simple steps:

  1. Identify your Experience Cloud tenant name and Target client code. Note that the tenant name and client code may be different for your organization.
    1. Tenant Name: Your tenant name is the subdomain part of your Experience Cloud URL. For example, if your Experience Cloud URL is mytenant.marketing.adobe.com, your tenant name is mytenant.
    2. Client Code: Your Target Client Code can be retrieved from the Target UI as described here.
  2. Create a Target Activity (A/B, XT, AP or Recommendations) using the Form-Based Composer
  3. Use the Server Side (or Batch) Delivery API to get response for the mboxes used in the Target Activity created in step 1.
  4. Present the experience to the visitor!

Note the following characteristics of the Delivery API:

  1. The delivery API enables you to get experiences/offers for an mbox and an audience segment in a RESTful manner.
  2. There is no authentication for Target Delivery APIs.
  3. This API does not process cookies or redirect calls.
  4. There is no notion of a “user role” in the Server Side Delivery API because it represents a call to fetch content or report events to Target edge servers.

Best Practices

  1. The response of the Delivery API includes the edgeHost parameter. This is the URL of the Target edge that served this request. All subsequent requests for this visitor/session should be sent to this edge.
  2. The session-id in the REST API must be unique for every visitor in your application.
  3. Use mboxTrace with a Debug Authentication Token to debug your API integrations. The Debug Authentication Token is valid for six hours and needs to be refreshed accordingly.
  4. You can pass user-agent in the request header in order to leverage browser and device based audience segmentations.

Input Parameters

Delivery API Sample Request. This is a request with just the mbox name in the POST body.

curl -X POST \
  'https://<your-client-code>.tt.omtrdc.net/rest/v1/mbox/my-session-id?client=<your-client-code>' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "mbox" : "my-mbox-name"
}'

Response for Sample Request

{
    "tntId": "111499796294071-449025.28_44",
    "edgeHost": "mboxedge28.tt.omtrdc.net",
    "content": "Use 10OFF for $10 off for orders over $100",
    "sessionId": "my-session-id"
}

Delivery API request with all possible inputs

curl -X POST \
  'https://<your-client-code>.tt.omtrdc.net/rest/v1/mbox/A210702C-402F-4458-9869-FCE64F318AE6?client=<your-tenant-name>' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.75.14 (KHTML, like Gecko) Version/7.0.3 Safari/7046A194A' \
  -d '{
  "mbox" : "a1-mobile-ab",
  "thirdPartyId" : "12345abcde",
  "profileParameters" : {
    "param1" : "value1",
    "param2" : "value2",
    "entity.id" : "entityId",
    "entity.name" : "entityName"
  },
  "mboxParameters" : {
    "screenHeight": 1057,
    "screenWidth": 1920,
    "browserWidth": 1040,
    "browserHeight": 960,
    "browserTimeOffset": 240,
    "colorDepth": 24,
    "mboxXDomain": "enabled",
    "mboxMCGVID": "91394045728588414913028121188926585416",
    "mboxAAMB": "cIBAx_aQzFEHcPoEv0GwcQ",
    "mboxMCGLH": 7,
    "vst.alias.id" : "2342345364532",
    "vst.alias.authState" : "1"
 },
  "requestLocation" : {
    "pageURL" : "http://demo/demo/store/",
    "referrerURL" : "http://demo/demo/store/",
    "ipAddress" : "128.10.10.1",
    "impressionId" : "15989",
    "host" : "staging-1"
  }
}'

Response for Delivery API request with all inputs

{
    "thirdPartyId": "12345abcde",
    "edgeHost": "mboxedge28.tt.omtrdc.net",
    "content": "Get 5% off using code 5OFF!",
    "sessionId": "A210702C-402F-4458-9869-FCE64F318AE6"
}

POST Request

The Server Side Delivery API only supports POST requests. Here is a sample POST call performed using the API.

https://your-client-code.tt.omtrdc.net/rest/v1/mbox/my-session-123?client=your-client-code

In this request,

my-session-123

This is the Session Id that should be generated and maintained by you. The Session Id can be any printable string except a space, ?, or /. It should be between 1 and 128 characters in length.

For a particular session, its value must stay the same across multiple requests.

Routing to a particular node in the edge cluster is done using Session Id.

**The session is active for 30 minutes on the server side. Therefore, you shouldn’t use a different SessionId for a particular tntId/thirdPartyId within 30 minutes of the last request made with the tntId/thirdPartyId. Otherwise, changes to the profile could be inconsistent and unpredictable.**

**Using the same Session ID with multiple tntIds/thirdPartyIds may cause unpredictable changes to the profiles identified by the tntId/thirdPartyIDs.**
your-client-code Your account’s client code. This parameter is mandatory for each request.

The list of parameters that you can supply in the body of the request.

Request Parameters

Parameter Description Default Value Validation
mbox The mbox name. None, it cannot be empty.

Same validation as for all mbox calls.

1 < Length < 250

Cannot contains any of the following characters: ’, “, %22, %27, <, >, %3C, %3E
clicked

Equivalent of using the ”-clicked" suffix in mbox names for mbox calls.

Click mboxes only work for campaigns with metrics that have a specific mbox selected, for example “click from homePageHer” and will not work if “click from display mboxes” is selected.

 

 False Can be empty or true/false
tntId New name for pcId/mboxPC.

Empty.

If no “thirdPartyId” was provided, a new tntId is generated and returned as part of the response. Otherwise remains empty.

1 < Length < 128

Cannot contain more than a single “.” (dot).

The only dot allowed is for profile location suffix.
thirdPartyId Client-provided visitor ID. Empty 1 < Length < 128
marketingCloudVisitorId Marketing Cloud Visitor ID Empty 1 < Length < 128
order > total Order amount associated with the order Empty If not empty, should be a valid decimal
order.id Order reference ID Empty If not empty, Length < 250
order > purchasedProductIds Order referenced product IDs Empty

Each ID cannot exceed 50 char length.

Total length of comma-delimited IDs as string cannot exceed 250 chars
profileParameters

Parameters that should be set in the profile.

The end values in the profile are saved as profile.param=value.

 Empty Cannot contain more than 50 parameters
profileParameters.[name] Profile parameter name Empty

Length < 128

Should not start with “profile.” prefix.
profileParameters.[value] Profile parameter value Empty Length < 256
mboxParameters Any mbox parameters that may need to be provided. eg. screenWidth. Empty

Cannot contain more than 50 parameters.

Cannot contain order-related parameters that should be set in “order”.

Cannot contain parameters with “profile.” prefix. Those should be set in “profileParameters”.
mboxParameters.[name] Mbox parameter name Empty Length < 128
mboxParameters.[value] Mbox parameter value Empty Length < 256
requestLocation > pageURL Equivalent to mboxURL mbox parameter Empty

Valid URL.

Length < 3072
requestLocation > referrerURL Equivalent to mboxReferrer mbox parameter Empty

Valid URL

Length < 3072
requestLocation > ipAddress Override the IP address of the client server IP address or the server making the call Valid IP address
requestLocation > impressionId

Equivalent of pageId.

A unique one is generated with each request if no value was specified.

 Empty Length < 128
requestLocation > host Equivalent of mboxHost “unknown” Length < 250
mboxTrace Enabled detailed tracing of the call for debugging False Empty/True/False

Response Parameteres

Field Path Description
sessionId Session ID that was provided for this call.
tntId Provided or generated tntId.
thirdPartyId thirdPartyId if one was provided.
mboxTrace Serialized mbox trace details.

Debugging the API

You can enable debugging in your API using mboxTrace by following these steps:

  1. Generate a Debug Authentication Token by following one of the following methods:
    1. Retrieve the Authroization Token using the Target UI as explained here.
    2. Use the Authentication Token API as described below.
  2. Set mboxTrace parameter as True in the API request

Identifying Visitors

Delivery Calls with differnt identifiers - Using a thirdPartyId

{
   "mbox" : "homePageHero",
   "thirdPartyId" : "customId-123"
}

Response when a thirdPartyId is provided

{
   "content" : "content",
   "sessionId" : "999888",
   "thirdPartyId" : "customId-123"
}

Request using the Marketing Cloud Visitor ID

{
   "mbox" : "homePageHero",
   "marketingCloudVisitorId" : "23131312312312123123"
}

Request using all three identifiers

{
   "mbox" : "homePageHero",
   "tntId" : "1234343422.17_01",
   "marketingCloudVisitorId" : "23131312312312123123"
}

There are a multiple ways in which a Visitor can be identified in Target. Target uses three identifiers

Learn how profiles are merged and synced in real time using the different identifiers.

Using the tntId

A tntId is generated if it isn’t provided in the request. See the Sample Request #1 on the right.

Note that a new tntId is generated and provided in the response. Subsequent requests need to include this TnT ID.

The tntId is not returned in the API response if a thirdPartyId or marketingCloudVisitorId is provided in the request.

Using Custom IDs

If you want to use Custom IDs to identify visitors (profiles), use the thirdPartyId. You must provide these IDs with every call.

Combining IDs

You can combine tntId/thirdPartyId/marketingCloudVisitorId and provide them in the same request. A typical scenario would be to provide tntId along with another ID.

Server Side Batch Delivery

Batch Overview

Batch Delivery Request with two mboxes and one prefetched mbox

curl -X POST \
  https://<your-client-code>.tt.omtrdc.net/rest/v2/batchmbox?client=<your-client-code>&sessionId=<sessionId> \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'session-id: your-unique-session-id'\
  -d '{
   "client": "<your-client-code>",
   "id": {
        "tntId": "123456789"
   },
   "mboxes": [
        {
            "indexId": 0,
            "mbox": "batch-req-1"
        },
        {
            "indexId": 1,
            "mbox": "batch-req-2"
        }
    ]
}'

Batch Delivery Response for two mboxes and one prefetched mbox

{
    "requestId": "77a45e19-732f-42ea-98de-e4a36ceecd55",
    "client": "<your-client-code>",
    "id": {
        "tntId": "123456789.28_3"
    },
    "edgeHost": "mboxedge28.tt.omtrdc.net",
    "contentAsJson": false,
    "mboxResponses": [
        {
            "mbox": "batch-req-1",
            "content": "batch-response-1a"
        },
        {
            "mbox": "batch-req-2",
            "content": "batch-response-2a"
        }
    ],
    "prefetchResponses": [
        {
            "mbox": "batch-req-3",
            "content": "batch-response-3a",
            "eventTokens": [
              "OXszbV+Odw+fblLkzmgrW2qipfsIHvVzTQxHolz2IpSCnQ9Y9OaLL2gsdrWQTvE5wM++BveH6AIK0pfQ2QUzsg=="
            ]
        }
    ]
}

The Batch Delivery API allows requesting content for multiple mboxes in a single call, therefore improving performance and flexibility in delivery. The Batch Delivery API has two capabilities, both of which can be used together:

  1. Batch Mbox: You can request the offers for multiple mboxes with a single API request. The behavior of this capability is same as the Delivery API for a single mbox.
  2. Prefetch: A prefetch mode that enables clients like mobile apps, servers etc to fetch content for multiple mboxes in one request, cache it locally and later notify Target when the user visits those mboxes.

Here are some common terms that you need to be familiar with when using the Batch Delivery API.

Known Limitations

Batch Input Parameters

Batch Delivery with all possible inputs

curl -X POST \
  https://<your-client-code>.tt.omtrdc.net/rest/v2/batchmbox?client=<your-client-code>&sessionId=<sessionId> \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'session-id: your-unique-session-id' \
  -H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.75.14 (KHTML, like Gecko) Version/7.0.3 Safari/7046A194A' \
  -d '{
   "client": "<your-client-code>",
   "host": "www.foo.com",
   "ipAddress": "1.2.3.4",
   "trace" : { 
        "enabled": true,
        "includeMetrics": true
   },
   "id": {
        "tntId": "123456789",
        "thirdPartyId": "32jh4jk23h4kj2",
        "marketingCloudVisitorId": "92387492387543875638",
        "customerIds": [
            {
                "id": "32jh4jk23h4kj2",
                "integrationCode": "userid",
                "authenticatedState": "authenticated"
            }
        ]
   },
   "aamParameters": {
        "blob": "32fdghkjh34kj5h43",
        "uuid": "82394234238798437",
        "dcsLocationHint": 9,
        "dataPartnerId": 86567576,
        "dataPartnerUserId": 348382232423424
   },
   "contentAsJson": true,
   "profileParameters": {
        "age": "18"
   },
   "prefetch": [
        {
            "indexId": 0,
            "mbox": "batch-req-1",
            "parameters": {
                "T_GHY": "7563"
            },
            "product": {
                "id": "54353",
                "categoryId": "93284230"
            },
            "order": {
                "id": "343",
                "total": 125.34,
                "purchasedProductIds": ["762", "1253", "499"]
            }
        }
   ],
   "mboxes": [
        {
            "indexId": 0,
            "mbox": "batch-req-2",
            "parameters": {
                "T_GHY": "7563333"
            },
            "product": {
                "id": "5431153",
                "categoryId": "9328114230"
            },
            "order": {
                "id": "34366",
                "total": 1425.34,
                "purchasedProductIds": ["7632", "12253", "4949"]
            },
            "requestLocation": {
                "pageURL": "http://foo.com/welcome-bing",
                "referrerURL": "https://bing.com"
            }
        }
   ],
   "notifications": [
        {
            "timestamp": 1485216216,
            "mbox": "batch-req-3",
            "parameters": {
                "ad": "1"
            },
            "eventTokens": ["OXszbV+Odw+fblLkzmgrWwreqXMfVUcUx0s/BHR5kCKCnQ9Y9OaLL2gsdrWQTvE5wM++BveH6AIK0pfQ2QUzsg=="],
            "order": {
                "id": "34",
                "total": 125.34,
                "purchasedProductIds": ["76", "125", "99"]
            },
            "product": {
                "id": "54353",
                "categoryId": "93284230"
            }
        }
    ],
    "mboxOverride": {
        "ip": "184.58.98.74",
        "time": 123654735,
        "visitorPercentage": 78.54,
        "aamResponse": "982374982738",
        "aamSegments": "34,1243,56443"
    }
}'
Field Name Required Validation
client Y Valid client code
trace N Enable mboxTrace for debugging by setting *enabled* as *true*
id → tntId N
  • Max size 128
  • Should not contain a dot, unless the dot delimits the location hint
id → thirdPartyId N Max size 128
id → marketingCloudVisitorId N Max size 128
id → customerIds N
  • No null elements
  • Max size 50
id → customerIds → id Y Max size 128
id → customerIds → integrationCode Y Max size 50
id → customerIds → authenticatedState Y unknown (default) | authenticated | logged_out
profileParameters N
  • Max count 50
  • no blank names
  • name size <= 128
  • value size <= 256
  • name should not start with “profile.”
environmentId N Valid client environment id
host N Equivalent to mboxHost mbox parameter. (Length < 128)
ipAddress N Request IP address, defaults to origin IP address.
contentAsJson N true | false
mboxes N
  • Max count 50
  • No null elements
mboxes → indexId Y
  • Not null
  • >= 0
mboxes → mbox Y
  • not blank
  • no ’-clicked’ suffix
  • max size 250
  • values not allowed: ’** display mboxes /**’, ’** any mbox **’, ’** click from display mbox **’
mboxes → clicked N
  • Not null
  • true or false
mboxes → parameters N Mbox parameters associated with this mbox.
  • max count 50
  • name not blank
  • name length <= 128
  • value length <= 5000
  • name should not start with “profile.”
  • not allowed names: “orderId”, “orderTotal”, “productPurchasedId”
mboxes → requestLocation → pageURL N Equivalent to mboxURL mbox parameter.
mboxes → requestLocation → referrerURL N Equivalent to mboxReferrer mbox parameter
mboxes → requestLocation → impressionId N Equivalent of pageId. A unique string (length < 128) is generated with each request if no value was specified.
mboxes → product N
mboxes → product → id N
  • Not null
  • max size = 128
mboxes → product → categoryid N
  • Not null
  • max size = 128
mboxes → order N
mboxes → order → id N
  • max length = 250
mboxes → order → total N
  • >= 0
mboxes → order → purchasedProducts N
  • No blank values
  • each value’s max length 50
  • total ids length <= 250
prefetch N
  • Max count 50
  • No null elements
prefetch → indexId Y
  • Not null
  • >= 0
prefetch → mbox Y
  • not blank
  • no ’-clicked’ suffix
  • max size 250
  • values not allowed: ’** display mboxes /**’, ’** any mbox **’, ’** click from display mbox **’
prefetch → parameters N
  • max count 50
  • name not blank
  • name length <= 128
  • value length <= 5000
  • name should not start with “profile.”
  • not allowed names: “orderId”, “orderTotal”, “productPurchasedId”
prefetch → product N -
prefetch → product -> id N
  • Not blank
  • max size = 128
prefetch → product → categoryId N
  • Not blank
  • max size = 128
prefetch → order N  
prefetch → order → id N max length = 250
prefetch → order → total N >= 0
prefetch → order → purchasedProductIds N
  • no blank values
  • each value’s max length 50
  • total ids length <= 250
notifications N Send notification requests for prefetched mboxes
notifications → type N hit | click; Default is “hit”
notifications → timestamp Y Indicates when the visitor visited the mbox. This should be a 10 digit UNIX timestamp in milliseconds.
notifications → mbox Y mbox name
notifications → parameters N Additional parameters with which the mbox was prefetched.
notifications → eventTokens N encrypted representation of the event to be taken from the response of the prefetch call.
notifications → clickToken N Encrypted representation of the click event to be taken from the response of the prefetch call.
notifications → profileScriptToken N Encrypted representation of the executed profile scripts map.
notifications → order N Accepts order details (id, total, purchasedProductIds) associated with this mbox notification.
notifications → product N Accepts product details (id, categoryId) associated with this mbox notification.

Integration with Adobe Audience Manager

Example: A sample request with AAM parameters.

{
    "aamParameters" : {
        "blob": "32fdghkjh34kj5h43",
        "uuid": "82394234238798437",
        "dcsLocationHint": 9,
        "dataPartnerId": 86567576,
        "dataPartnerUserId": 348382232423424
    }
}

You can send AAM parameters with the Batch Mbox API to leverage AAM Audience Segments.

Field Name Required Description
dcsLocationHint Y DCS Location Hint is used to determine which AAM DCS Endpoint to hit in order to retrieve the profile. Must be >= 1.
uuid N AAM Unique user identifier is the internal AAM ID used to uniquely identify a user id. Must not be blank.
dataPartnerId N AAM Data Partner ID is the ID for a Data Partner. Must be >=1.
dataPartnerUserId N AAM Data Partner Unique User Identifier is the user ID provided by a Data Partner. It must be a string.
blob N AAM Blob is used to send additional data to AAM. Must not be blank and the size <= 1024.

A4T for Batch Delivery API

Example 1: Response when a A4T-enabled campaign qualifies for the mbox/prefetch request.

{
   ...
   "mboxResponses":[ 
      { 
         "mbox":"homePageHero1",
         "content": "some content",
         "clientSideAnalyticsLoggingPayload": {
            "pe": "tnt",
            "tnta": "86492:0:0|0,86492:0:0|2,86492:0:0|1"
         }
      }
   ],
   "prefetchResponses":[ 
      { 
         "mbox":"homePageHero2",
         "content": "some content",
         "eventTokens": [...],
         "clientSideAnalyticsLoggingPayload": {
            "pe": "tnt",
            "tnta": "86494:0:0|0,86494:0:0|2,86494:0:0|1"
         }
      }
   ]
}

Example 1: Sample request to the Analytics Tracking Server with the Target A4T Payload

curl -X GET \
'https://<Analytics_Tracking_Server>/b/ss/<Report_Suite_IDs>/0/<Code_Version>?pe=tnt&tnta=86492:0:0|0,86492:0:0|2,86492:0:0|1,86494:0:0|0,86494:0:0|2,86494:0:0|1&mcid=<Marketing_Cloud_ID>&vid=<Custom_Visitor_ID>&aid=<Analytics_ID>'

In case any qualifying campaign is A4T enabled - target will send offer content containing also a payload (under a variable clientSideAnalyticsLoggingPayload) that should be logged by the client in Analytics using the Data Insertion API. A sample Target response and corresponding Analytics request is shown in the example alongside.

Field Name Required Description
Analytics_Tracking_Server Y The Analytics Tracking Server used in Target Reporting Destination.
Report_Suite_IDs Y The Report Suite ID for the Report Suite used for the Target Activity. Multiple report suite IDs can be provided in a comma separated format.
tnta Y Analytics payload (under the tnta variable) returned by Target server in clientSideAnalyticsLoggingPayload. Multiple payloads can be provided in a comma separated format.
mcid N Marketing Cloud Visitor ID. This is optional, but recommended.
vid N Custom Visitor ID
aid N Analytics ID

Note that the API used above is the Adobe Analytics Data Insertion API that can also be used as a POST request outlined here.

Best Practices for Batch Delivery

Mbox response for a qualifying campaign with a click metric

{
    "mboxResponses": [
        {
            "mbox": "homePageHero1",
            "content": "123",
            "clickToken": "1d2r"
        }
    ]
}

Sample notification request for a mbox click event

{
   "notifications": [
      {
         "type": "click",
         "timestamp": 1505944567000,
         "mbox": "homePageHero1",
         "clickToken": "1d2r"
      }
   ]
}
  1. It is not necessary to have all three kind of mboxes in a request. You can make a request for just a single mbox using this API.
  2. Note that the profileParameters are set at the top level of a Batch request and all mboxes, prefetch or regular, will be associated with the same visitor profile.
  3. When working with multiple mboxes in the batch mbox request, the Target edge will process the mboxes in the sequence specified by the IndexId parameter value.
  4. Overriding Parameters: You can override mbox parameters, such as IP, time.
  5. Prefetch: Fetch offers associated with an mbox in advance without incrementing the impression or visit/visitor count.
    1. Make sure you manage the eventTokens associated with an mbox for use at the notifications stage.
    2. When the qualifying campaign has a click metric defined for an mbox, then the clickToken will be returned in the response. When the visitor clicks the mbox and a notification request is sent, the notification type should be set to click and the corresponding clickToken should be included.
  6. Notifications: There are two kinds of notifications - hit and click.
  7. Profile Scripts are executed per each mbox inside mboxes, prefetch and notifications, as per the following logic:
    1. Regular mbox (part of the mboxes array): Profile Scripts are executed and results persisted in the profile immediately. Note that the sequence of execution will be as per the IndexId of the mboxes.
    2. Prefetch mbox (part of the prefetch array): Target will execute the profile scripts and cache it without persisting it to the profile. A profileScriptToken will be returned in the response and should be included in the notification request for this mbox. The results will be persisted into the profile at this time.
    3. Notification mbox (part of the notification array): If the notification has the profileScriptToken, then the profile script values will be written to the profile without re-executing them. If the profileScriptToken is missing then the profile scripts will be executed and again and persisted to the profile.
  8. If Response Tokens are enabled, they will be returned for each mbox response in the mboxes and prefetch sections.