openapi: 3.2.0
info:
  title: 'Emarsys Core API - External Content endpoint batch Https: API'
  description: In this batch you may find endpoints related to External Content.
  version: v2
servers:
- url: https://api.emarsys.net/api
security:
- X-WSSE: []
tags:
- name: '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
      responses:
        '200':
          description: ''
          content:
            application/json:
              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
              example:
                content:
                - date_of_birth: '1990-01-01'
                  season: winter
                  generated_image_url: https://customer.com/personal-images/ea6b95d41f8
                  age: '30'
            application/gzip:
              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
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      requestBody:
        content:
          application/json:
            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
      tags:
      - 'Https:'
components:
  securitySchemes:
    X-WSSE:
      type: apiKey
      name: X-WSSE
      in: header