SAP Emarsys Event API

openapi: 3.2.0
info:
  title: Emarsys Core API - Events endpoint batch Event API
  description: In this batch you may find endpoints related to events.
  version: v2
servers:
- url: https://api.emarsys.net/api
tags:
- name: Event
paths:
  /v2/event:
    post:
      summary: Create an External Event
      description: Creates an external event with the specified name in order to allow your external program, such as a CMS or CRM to trigger an Emarsys event.
      operationId: createExternalEvent
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                    created:
                      type: string
                      description: Creation date of the external event
                    replyCode:
                      type: integer
                      description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      id:
                        type: integer
                        description: The identifier of the external event.
                      name:
                        type: string
                        description: The name of the external event.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the external event.
              required:
              - name
              x-examples:
              - name: bulk purchasing
      tags:
      - Event
  /v2/event/:
    get:
      summary: List External Events
      description: Lists external event names and identifiers. Use the returned identifiers to trigger emails or programs.
      operationId: listExternalEvents
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: array
                    description: The requested data.
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The identifier of the external event.
                        name:
                          type: string
                          description: The name of the external event.
                        created:
                          type: string
                          description: The creation date of the external event.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Event
  /v2/event/{eventId}:
    get:
      summary: Query an External Event
      description: Returns the name of the external event specified by its identifier.
      operationId: QueryExternalEvent
      parameters:
      - name: eventId
        in: path
        description: The identifier of the external event.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: array
                    description: The requested data.
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The identifier of the external event.
                        name:
                          type: string
                          description: The name of the external event.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Event
    post:
      summary: Update an External Event
      description: Updates the name of an external event.
      operationId: updateExternalEvent
      parameters:
      - name: eventId
        in: path
        description: The identifier of the external event.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      id:
                        type: integer
                        description: The identifier of the external event.
                      name:
                        type: string
                        description: The name of the external event.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the external event.
              required:
              - name
              x-examples:
              - name: response_email
      tags:
      - Event
  /v2/event/{eventId}/usages:
    get:
      summary: List Uses of an External Event
      description: 'Lists the identifiers of the automation programs and emails that the specified external event triggers or is used in. Returns Automation Center and Interactions program identifiers and email identifiers.


        **Note:** Emails must be in the *launched* state in order to appear.'
      operationId: listUsesOfExternalEvent
      parameters:
      - name: eventId
        in: path
        description: The identifier of the external event.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      program_ids:
                        type: array
                        description: The Automation Center program identifier.
                        items:
                          type: integer
                      email_ids:
                        type: array
                        description: The email identifier.
                        items:
                          type: integer
                      interactions_program_ids:
                        type: array
                        description: 'The Interactions program identifier. '
                        items:
                          type: string
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Event
  /v2/event/{eventId}/delete:
    post:
      summary: Delete an External Event
      description: 'Deletes an external event.


        **Note:** Deleting an event has no effect on any programs or email campaigns linked to the event.'
      operationId: deleteExternalEvent
      parameters:
      - name: eventId
        in: path
        description: The identifier of the external event.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Event
  /v2/event/{eventId}/trigger:
    post:
      summary: Trigger an External Event
      description: Activates a named external event trigger for a specified contact.
      operationId: triggerExternalEvents
      parameters:
      - name: eventId
        in: path
        description: The identifier of the external event.
        required: true
        schema:
          type: integer
      responses:
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        200(a):
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        200(b):
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/http-200-responses.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/http-200-responses.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/http-200-responses.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      ids:
                        type: array
                        description: The array of identifiers of successfully triggered contacts.
                        items:
                          type: string
                      errors:
                        type: object
                        description: Indicates that an error occurred during triggering the listed contacts identified by the value of the specified `key_id`.
        200(c):
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/http-200-responses.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/http-200-responses.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/http-200-responses.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      connectedTo:
                        type: object
                        description: Indicates whether the event has triggered any emails, AC, or Interactions programs. Only executable programs are listed. This object becomes `false` if the customer is triggering an External event that is not triggering **any** executable Automation programs or email campaigns.
                        properties:
                          email:
                            type: boolean
                            description: '*true*: the event triggered an email.'
                          acProgram:
                            type: boolean
                            description: '*true*: the event triggered an AC program.'
                          interactionsProgram:
                            type: boolean
                            description: '*true*: the event triggered an Interaction program.


                              This field is only returned if the *Real Time Interaction* feature is enabled for the customer.'
        200(d):
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/http-200-responses.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/http-200-responses.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/http-200-responses.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      ids:
                        type: array
                        description: The array of identifiers of successfully triggered contacts.
                        items:
                          type: string
                      errors:
                        type: object
                        description: Indicates that an error occurred during triggering the listed contacts identified by the value of the specified `key_id`.
                      connectedTo:
                        type: object
                        description: Indicates whether the event has triggered any emails, AC, or Interactions programs. Only executable programs are listed. This object becomes `false` if the customer is triggering an External event that is not triggering **any** executable Automation programs or email campaigns.
                        properties:
                          email:
                            type: boolean
                            description: '*true*: the event triggered an email.'
                          acProgram:
                            type: boolean
                            description: '*true*: the event triggered an AC program.'
                          interactionsProgram:
                            type: boolean
                            description: '*true*: the event triggered an Interaction program.


                              This field is only returned if the *Interaction* feature is enabled for the customer.'
        400(a):
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  replyCode:
                    type: integer
                  replyText:
                    type: string
                    description: Invalid event time format.
                  data:
                    type: string
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                key_id:
                  description: 'Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`.


                    When `id` or `uid` is used as identifier, provide value in this parameter and specify the the actual `id` or `uid` in the `external_id` parameter.'
                  oneOf:
                  - type: string
                  - type: integer
                contacts:
                  type: array
                  description: The contacts to trigger in a batch call.
                  items:
                    type: object
                    properties:
                      external_id:
                        type: string
                        description: 'The external identifier of the field specified in the `key_id` parameter.


                          **Tip:** Get the contact identifier at the [Get Contact Data](/reference/openapi.json/paths/~1v2~1contact~1getdata/post) endpoint.'
                      trigger_id:
                        type: string
                        description: 'An **optional**  unique identifier for each trigger, used for deduplication in Interactions.


                          If an event is sent multiple times with the same `trigger_id` in Interactions, only the first one will be processed. If these IDs differ or are missing, the triggers are considered different, and all of them will be processed.


                          We are adding the same functionality to AC programs, so you need to send different IDs, or not send any. Otherwise some events may not be processed in AC programs because of the identical IDs. Only send the same ID again if a previously failed trigger needs to be retried.


                          `trigger_id` is different from `event_id`. `trigger_id` identifies an individual request **not** the source event.'
                      data:
                        type: object
                        description: 'The external data used for the trigger.


                          The example payload shows the following scenario. If the email template is prepared properly, the `itemName`and `itemPrice` placeholders is replaced by the values in the email campaign, which is sent to the specified contacts.'
                      attachment:
                        type: string
                        description: 'The email attachment.


                          **Note:** For details and limitations, see [Using Attachments](https://help.emarsys.com/hc/en-us/articles/115004461489-triggered-email-end-user-guide#using-attachments).'
                      event_time:
                        type: string
                        description: 'If the format matches one of these: 2007-03-01T13:00:00Z or 2007-03-01T13:00:00.000Z, we will use that as event time in Interactions. If event time is not provided, we will continue to use the time when the event was processed by us. If invalid event time is provided (it is set, but not matching the above formats) an error will be provided and the event won''t trigger either email, AC program, or be used in Interactions. Event time is checked at the same level as trigger_id, e.g. in the first level for single contact case and within the contacts array for batch use case.'
                    required:
                    - external_id
              required:
              - key_id
              x-examples:
              - key_id: veniam deserunt dolor dolor cupidatat
                contacts:
                - attachment: sint anim
                - event_time: ipsum
                  attachment: nostrud Duis
                  trigger_id: cillum nostrud eu sit est
                  external_id: eiusmod
      tags:
      - Event
components:
  schemas:
    default-response:
      type: object
      title: Default Response
      description: 'See the following documents for details on the error codes:


        - [HTTP 200 errors](docs/response-codes/http-200-responses.md)

        - [HTTP 400 errors](docs/response-codes/http-400-errors.md)

        - [HTTP 401-429 errors](docs/response-codes/http-401-429-errors.md)

        - [HTTP 500 errors](docs/response-codes/http-500-errors.md)'
      properties:
        replyCode:
          type: integer
          description: The Emarsys response code. Successful requests return *0*; otherwise, see [errors](docs/response-codes/http-400-errors.md).
          default: 0
        replyText:
          type: string
          description: Additional information on the status of the request.
        data:
          description: Contains the requested data, if applicable.
          oneOf:
          - type: string
          - type: integer
          - {}
          - type: object
            properties:
              ? ''
              : type: object
      x-examples:
      - replyCode: 0
        replyText: OK
        data: {}
  securitySchemes:
    X-WSSE:
      type: apiKey
      name: X-WSSE
      in: header