Asynchronous Merge Trigger Email API

The Asynchronous Merge Trigger Email API has a different service URL than the standard Merge Trigger Email API, but it uses the same parameters, header, and request body. The response is different: it provides the data necessary to use the Polling API endpoint results.

Note: The Asynchronous API is generally available for all Responsys customers.

Service URL:

/rest/asyncApi/v1.3/campaigns/{campaignName}/email

Required Path Parameters:

campaignName - Name of the email campaign to send to the recipients

Request Method:

POST

Request Header:

Authorization=<AUTH_TOKEN>

Content-Type=application/json

Message-Expiration=<ttl value – if omitted, the system uses the default of 3600 seconds. Use this value to set an expiration time for your request.>

Request Body Notes:

• You can learn about the required parameters in the Merge Trigger Email REST Endpoints page. View the Request section of the topic.

• This endpoint supports sending reference data in requests. To learn how you can retrieve this data when polling, refer to Returning reference data for asynchronous requests.

Sample Request Body:

{
  "mergeTriggerRecordData": {
    "fieldNames": [
      "EMAIL_ADDRESS_"
    ],
    "mergeTriggerRecords": [
      {
        "fieldValues": [
          "john.doe@oracle.com"
        ],
        "optionalData": [
          {
            "name": "CITY_",
            "value": "Redwood City"
          },
          {
            "name": "MOBILE_NUMBER_",
            "value": "12345678933"
          }
        ]
      },
      {
        "fieldValues": [
          "george.washington@oracle.com"
        ],
        "optionalData": [
          {
            "name": "CITY_",
            "value": "Vancouver"
          },
          {
            "name": "MOBILE_NUMBER_",
            "value": "12345678934"
          }
        ]
      }
    ]
  },
  "referenceData": {
    "key": "value"
  },
  "mergeRule": {
    "insertOnNoMatch": false,
    "updateOnMatch": "NO_UPDATE",
    "matchColumnName1": "EMAIL_ADDRESS_",
    "matchColumnName2": "",
    "matchColumnName3": "",
    "matchOperator": "NONE",
    "optinValue": "I",
    "optoutValue": "O",
    "htmlValue": "H",
    "textValue": "T",
    "rejectRecordIfChannelEmpty": "E",
    "defaultPermissionStatus": "OPTIN"
  }
}

Response Notes:

• The system validates the request payload syntax to ensure that the payload is well-formed JSON. However, it does not validate correctness of the values. For example, it does not validate if the campaign object exists or not, nor does it validate whether the payload uses the correct property names. Subsequently, you must poll for results to learn whether the request succeeded or failed due to other reasons.
• A successful response for the asynchronous API returns an HTTPS status code of 202 Accepted.
• The response body contains the information you need to analyze the response that you would get from the Polling API.
  • requestId: Unique identifier of the API request. The value is alphanumeric.
  • apiName: Name of the API request that you triggered. Always asyncMergeTriggerEmail for this API request’s response.
  • status: When successful, the status value is REQUEST_ACCEPTED. This means that the payload syntax was well-formed JSON and that the request was placed in the system queue for processing. You must poll for the final result; for more information, see Polling API endpoint.
• See Common error responses for the Asynchronous API for details about the error responses.

Sample Successful Response:

{
    "requestId": "SkxIMG1YOjoxNTIxNzg3ODM0",
    "apiName": "asyncMergeTriggerEmail",
    "status": "REQUEST_ACCEPTED"

"links":  [
        {
            "rel": "self",
            "href": "/rest/asyncapi/v1.3/campaigns/myEmailCmpn/email",
            "method": "POST"
        },
        {
            "rel": "asyncResponse",
            "href": "/rest/asyncapi/v1.3/requests/SkxIMG1YOjoxNTIxNzg3ODM0",
            "method": "GET"
        }
    ]
}

Sample Error Response - Queue is Full:

{
    "type": "",
    "title": "Unable to submit Async request",
    "errorCode": "UNABLE_TO_SUBMIT_ASYNC_REQUEST",
    "detail": "Error in submitting aysnc request",
    "errorDetails": []
}

Learn more

Common error responses for the Asynchronous API

Merge members into a profile list and trigger email messages to them

Returning reference data for asynchronous requests