swagger: '2.0'
info:
  title: Emarsys Core API - External Content endpoint batch
  description: In this batch you may find endpoints related to External Content.
  version: v2
host: api.emarsys.net
basePath: /api
schemes:
  - https
paths:
  '/https://{customer-website.com}/api/example/':
    post:
      summary: Request External Content for Personalization
      description: "### Basics\n\nWith External Content, you can use your own API to personalize content in your messages.\n\nIn this scenario, Emarsys calls your API by sending a POST request.\n\nIn the following example, we are going to request information that is not present in the Emarsys Database.\n\n\nImagine that the following attributes (key-value pairs) describe a specific record in your database:\n- **email=john@example.com**\n- **external_id=90210**\n- *title=Footbal shirt*\n- *price=100*\n- *image_url=https://example.com/images/football-shirt.png*\n\nIn the Emarsys Database, only the first two: **email=john@example.com** and **external_id=90210** are available. (The purchase history of this contact is stored in your database only.)\n\n\n#### Request logic and contents\n\n\"*For records where **email=john@example.com** and **external_id=90210**, return the values for **title**, **price**, and **image_url**, requesting a maximum of <**limit**> number of content objects per reference field.*\"\n\n***parameters*** (reference fields):\n- *email=john@example.com*\n- *external_id=90210*\n\n***fields*** (response fields, the keys we expect values for):\n\n- *title*\n- *price*\n- *image_url*\n\n***limit*** (for the returned content per reference field)\n\n___\n\n#### Response contents\n\n***content***:\n- *email=john@example.com*\n- *external_id=90210*\n- *title=Football shirt*\n- *price=100*\n- *image_url=https://example.com/images/football-shirt.png*\n---\n\n### Request\n\n<dl>\n  <dt>parameters</dt>\n  <dd>\n  \n  - This array lists the preconfigured *reference fields* and their values.</dd>\n  <dt>fields</dt>\n  <dd>\n  \n  - This array lists  the expected response fields configured on the UI.</dd>\n  <dt>limit</dt>\n  <dd>\n  \n  - Indicates how many personalization values we expect to get for each contact from your API (if there are multiple values for the same response field).\n  \n  \n  - Value automatically calculated value during the personalization process (based on your e-mail template). For example, if your system calculates a product recommendation and you use 3 recommendations, the limit value is automatically set to 3.</dd>\n  \n\n**NOTE**: Basic HTTP authentication and OAuth2 are supported.\n\n**IMPORTANT**:\nThe request will always be in batch and can contain up to 1000 contacts (maximum 100 paralelly at a time per host).\n\n***Request structure***\n\n```\n{\n\t\"parameters\": [\n\t\t{\n\t\t\t\"<reference-field-1>\": \"<reference-value-1_1>\",\n\t\t\t\"<reference-field-2>\": \"<reference-value-2_1>,\"\n\t\t\t...\n\t\t},\n\t\t{\n\t\t\t\"<reference-field-1>\": \"<reference-value-1_2>\",\n\t\t\t\"<reference-field-2>\": \"<reference-value-2_2>\",\n\t\t\t...\n\t\t},\n\t\t...\n\t],\n\t\"fields\": [\n\t\t\"<response-field-1>\",\n\t\t\"<response-field-2>\",\n\t\t...\n\t],\n\t\"limit\": <automatically-calculated-limit>\n}\n```\n\n\n***Request example***\n\n```\n{\n\t\"parameters\": [\n\t\t{\n\t\t\t\"email\": \"john@example.com\",\n\t\t\t\"external_id\": \"92010\"\n\t\t},\n\t\t{\n\t\t\t\"email\": \"jane@example.com\",\n\t\t\t\"external_id\": \"21235\"\n\t\t}\n\t],\n\t\"fields\": [\n\t\t\"title\",\n\t\t\"price\",\n\t\t\"img_url\"\n\t],\n\t\"limit\": 3\n}\n```\n\n---\n\n### Response\n\nThe response must contain a **content** array, which contains all personalization data. Every object in the array must belong to a contact.\n\n- Maximum response body size: *2MB*\n- Supported response type:\n*gzip-encoded* (suggested)\n\n**IMPORTANT**\n\n- Nested objects and arrays placed inside the content objects are considered as a syntactical error, resulting in the whole response being discarded. \n- Response fields that were not specified on the configuration screen will be discarded. The same happens if you exceed the number per contact (per reference field) set in **limit**.\n\n***Response structure***\n```\n{\n\t\"content\": [\n\t\t{\n\t\t\t\"<reference-field-1>\": \"<reference-value-1_1>\",\n\t\t\t\"<reference-field-2>\": \"<reference-value-2_1>\",\n\t\t\t...\n\t\t\t\"<response-field-1>\": \"<response-value-1_1>\",\n\t\t\t\"<response-field-2>\": \"<response-value-2_1>\",\n\t\t\t...\n\t\t},\n\t\t{\n\t\t\t\"<reference-field-1>\": \"<reference-value-1_2>\",\n\t\t\t\"<reference-field-2>\": \"<reference-value-2_2>\",\n\t\t\t...\n\t\t\t\"<response-field-1>\": \"<response-value-1_2>\",\n\t\t\t\"<response-field-2>\": \"<response-value-2_2>\",\n\t\t\t...\n\t\t},\n\t\t...\n\t],\n}\n```\n\n***Response example***\n\n```\n{\n\t\"content\": [\n\t\t{\n\t\t\t\"email\": \"john@example.com\",\n\t\t\t\"external_id\": \"90210\"\n\t\t\t\"title\": \"Football shirt\",\n\t\t\t\"price\": 100,\n\t\t\t\"img_url\": \"https://example.com/images/football-shirt.png\"\n\t\t},\n\t\t{\n\t\t\t\"email\": \"jane@example.com\",\n\t\t\t\"external_id\": \"21235\"\n\t\t\t\"title\": \"Bicycle\",\n\t\t\t\"price\": 120,\n\t\t\t\"img_url\": \"https://example.com/images/bicycle.png\"\n\t\t},\n\t\t{\n\t\t\t\"email\": \"bill@example.com\",\n\t\t\t\"external_id\": \"42469\"\n\t\t\t\"title\": \"Baseball cap\",\n\t\t\t\"price\": 50,\n\t\t\t\"img_url\": \"https://example.com/images/baseball-cap.png\"\n\t\t}\n\t]\n}\n```\n\n---\n\n### Error handling\n\nIf External Content doesn't receive a preconfigured response field, we will treat it as missing personalization.\n\nUpon receiving a request from Emarsys via External Content, if you cannot send back the personalized content, do not send back any content about the contact that cannot be personalized.\n\n**Blocking errors**\n\nSome errors may result in paused or aborted Automation Center (AC) or Interactions campaigns.\n\nAC and Interactions programs using personalization tokens built with External Content are paused or aborted in the following cases:\n\n- Any of the requests fails with a 4xx status code, except for 429 or 408;\n- The response body is not a valid JSON document;\n- The response format violates the  requirements;\n- The response body contains insufficient data (not all parameters/ reference fields are echoed back in the content items), as in the following example:\n\n\nRequest body:\n```\n{\n   \"parameters\": [\n       {\n           \"email\": \"aaa@example.com\",\n           \"UID\": \"1234\"\n       }\n   ],\n   \"fields\": [\n       \"img_url\"\n   ],\n   \"limit\": 1\n}\n```\n**Incorrect** response body (the UID parameter is missing):\n```\n{\n   \"content\": [\n       {\n           \"email\": \"aaa@example.com\",\n           \"img_url\": \"https://example.com/images/example.png\"\n       }\n   ]\n}\n```\n\n**Retrying requests**\n\nIf there are no blocking errors, the requests will be retried. Examples include:\n\n-\tthe configured endpoint is unreachable;\n-\tthe request times out;\n-\tthe status code is 5xx (server error);\n-\tthe status code is 429 (too many requests);\n-\tthe status code is 408.\n\nYou can find the comprehensive list of all Emarsys error codes in [Response codes](docs/response-codes/error-codes.md)."
      operationId: requestExternalContent
      produces:
        - application/json
        - application/gzip
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              parameters:
                type: array
                description: This array lists the preconfigured Reference fields and their values returned by Emarsys during personalization.
                items:
                  type: object
                  properties:
                    '{reference-field-1}':
                      type: string
                    '{reference-value-1_N}':
                      type: string
                    '{reference-field-2}':
                      type: string
                    '{reference-value-2_N}':
                      type: string
                  required:
                    - '{reference-field-1}'
                    - '{reference-value-1_N}'
              fields:
                type: array
                description: 'This array lists the expected response fields, which were configured in the Response fields section.'
                items:
                  type: string
                  pattern: '^[A-Za-z][A-Za-z0-9_]*$'
              limit:
                type: integer
                description: |-
                  This value indicates how many personalization values we expect to get for a contact from your API. It is an automatically calculated value by during personalization based on your email template.

                  **Example**: Your system calculates a product recommendation and you use 3 recommendations in your email template. We will set the limit value automatically to 3, as you don't use more than 3 recommendations in your template.
            required:
              - parameters
              - fields
              - limit
            x-examples:
              - parameters:
                  - date_of_birth: '1990-01-01'
                    season: winter
                fields:
                  - generated_image_url
                  - age
                limit: 10
      schemes:
        - https
      responses:
        '200':
          description: ''
          schema:
            type: object
            properties:
              content:
                type: array
                items:
                  type: object
                  properties:
                    '{reference-field-1}':
                      type: string
                      description: 'Reference fields work as a key in the response, identifying an individual contact. If External Content receives a key which was not in the request, it will discard the objects identified by the unknown key.'
                    '{reference-field-2}':
                      type: string
                    '{response-value-1_N}':
                      type: string
                      description: The response fields containing the requested values.
                    '{response-value-2_N}':
                      type: string
                  required:
                    - '{reference-field-1}'
                    - '{reference-field-2}'
            required:
              - content
          examples:
            application/json:
              content:
                - date_of_birth: '1990-01-01'
                  season: winter
                  generated_image_url: 'https://customer.com/personal-images/ea6b95d41f8'
                  age: '30'
      security:
        - X-WSSE: []
parameters:
  'trait:filter:filter':
    name: filter
    in: query
    type: string
  'trait:limit10K:limit':
    name: limit
    in: query
    description: Specifies the maximum number of records to return.
    type: integer
    default: 10000
    maximum: 10000
    minimum: 1
  'trait:offset:offset':
    name: offset
    in: query
    description: Specifies an offset for pagination. The offset of the first record is *0*.
    type: integer
    default: 0
  'trait:limit1M:limit':
    name: limit
    in: query
    description: Specifies the maximum number of records to return.
    type: integer
    default: 1000000
    maximum: 1000000
    minimum: 1
  'trait:interval:start_date':
    name: start_date
    in: query
    description: |-
      Returns results from the specified date.

      **Accepted formats:** YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM, YYYY-MM-DD
    type: string
  'trait:interval:end_date':
    name: end_date
    in: query
    description: |-
      Returns results until the specified date.

      **Accepted formats:** YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM, YYYY-MM-DD
    type: string
  'trait:excludeEmptyResults:excludeempty':
    name: excludeempty
    in: query
    description: |-
      If `true`, contacts with a null or empty value in the specified field are not returned.

      **Note:** Any value except for `true` is interpreted as false.
    type: boolean
  'trait:limit10M:limit':
    name: limit
    in: query
    description: Specifies the maximum number of records to return.
    type: integer
    default: 10000000
    maximum: 10000000
    minimum: 1
  'trait:limit1MRequired:limit':
    name: limit
    in: query
    description: Specifies the maximum number of records to return.
    required: true
    type: integer
    default: 1000000
    maximum: 1000000
    minimum: 1
  'trait:limit1K:limit':
    name: limit
    in: query
    description: Specifies the maximum number of records to return.
    type: integer
    default: 1000
    maximum: 1000
    minimum: 1
securityDefinitions:
  X-WSSE:
    type: apiKey
    name: X-WSSE
    in: header
security:
  - X-WSSE: []