---
openapi: 3.0.0

info:
  title: Trigger campaigns using APIs
  description: "Interactive Message Execution API helps you with messaging capabilities. Using this REST API, you can send marketing or transactional messages using a Campaign Id using Email, SMS and Push channels. You will need the Campaign ID to send message using API.<br/><br/><b>Related documentation:</b><br/> To learn more about the API triggered Campaign creation flow and supported channels, refer to the [product documentation](https://experienceleague.adobe.com/en/docs/journey-optimizer/using/campaigns/api-triggered-campaigns/api-triggered-campaigns).<br/><br/><b>Code examples:</b><br/>Examples of how to trigger Campaigns using various channels are available on [this page](https://developer.adobe.com/journey-optimizer-apis/references/messaging-samples).<br/><br/><b>API path:</b><br/>Base path for Interactive Message Execution APIs: https://platform.adobe.io/ajo/im/executions<br/>Example of a complete path: https://platform.adobe.io/ajo/im/executions/unitary<br/><br/><b>Required headers:</b><br/>All calls require the headers Authorization, x-gw-ims-org-id, and x-api-key. For more information on how to obtain these values, see the [authentication tutorial](https://developer.adobe.com/journey-optimizer-apis/references/authentication).<br/><br/><b>Call timeout</b><br/>The call to the Interactive Message Execution REST API has a timeout of 60 sec. However internal retries are in place in case of unexpected timeouts to guarantee the delivery."
  version: "1.0.1"
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'

security:
  - imsUserToken: [ ]

servers:
  - url: https://platform-stage.adobe.io/ajo
    description: Stage Environment
  - url: https://platform.adobe.io/ajo
    description: Production Environment

paths:
  /im/executions/unitary:
    parameters:
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'

    post:
      summary: "Trigger an unitary message execution."
      tags:
        - execution
      operationId: postIMUnitaryMessageExecution
      security:
        - imsUserToken: [ ]
      description: ""
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/imExecutionRequestUnitary'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/imExecutionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '503':
          description: Personalized attachment resolution is temporarily unavailable (error code 160028). Retry the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  /im/executions/audience:
    parameters:
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'

    post:
      summary: "Trigger or Schedule an Audience Based Message execution."
      tags:
        - execution
      operationId: postIMAudienceMessageExecution
      security:
        - imsUserToken: [ ]
      description: ""
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/imExecutionRequestAudience'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/imExecutionResponse'
                  - $ref: '#/components/schemas/ScheduledExecutionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  /im/executions/audience/{executionId}:
    parameters:
      - name: executionId
        in: path
        description: execution id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
    get:
      summary: "Get Execution Status for Audience Based Message executions."
      tags:
        - execution
      operationId: getBatchExecutionStatusByExecutionId
      security:
        - imsUserToken: [ ]
      description: ""
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/executionStatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  /im/executions/schedules/{scheduleId}:
    parameters:
      - name: scheduleId
        in: path
        description: schedule id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
    get:
      summary: "Get Execution Status for Audience Based Message executions."
      tags:
        - execution
      operationId: getBatchExecutionStatusByScheduleId
      security:
        - imsUserToken: [ ]
      description: ""
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledExecutionResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
    delete:
      summary: "Delete a scheduled campaign execution."
      tags:
        - execution
      operationId: deleteScheduledExecution
      security:
        - imsUserToken: [ ]
      description: "Deletes a scheduled campaign execution before it has been triggered."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: "Empty response for successful deletion"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  /im/executions/highthroughput:
    parameters:
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'

    post:
      summary: "Trigger an unitary high throughput message execution."
      tags:
        - execution
      operationId: postIMUnitaryHAMessageExecution
      security:
        - imsUserToken: [ ]
      description: ""
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/imExecutionRequestHighThroughput'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/imExecutionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '503':
          description: Personalized attachment resolution is temporarily unavailable (error code 160028). Retry the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  /im/health:
    parameters:
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'

    get:
      summary: "Health of Unitary API Service"
      tags:
        - health
      security:
        - imsUserToken: [ ]
      description: "Health of Unitary API Service"
      responses:
        '200':
          description: Health Response

components:
  securitySchemes:
    imsUserToken: # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT    # optional, arbitrary value for documentation purposes
  parameters:
    x-api-key:
      name: x-api-key
      description: The API key belonging to the calling client.
      required: true
      in: header
      schema:
        type: string
    x-request-id:
      name: x-request-id
      description: A unique id generated by Adobe.io. This parameter will be auto-generated, do not include it in your payload.
      required: false
      in: header
      schema:
        type: string
    x-gw-ims-org-id:
      name: x-gw-ims-org-id
      description: The ims org id for which the action is being taken.
      required: true
      in: header
      schema:
        type: string
    x-sandbox-id:
      name: x-sandbox-id
      description: Platform Sandbox id.
      required: false
      in: header
      schema:
        type: string
    x-sandbox-name:
      name: x-sandbox-name
      description: >-
        Provides the platform Sandbox Name
      required: true
      in: header
      schema:
        type: string

  schemas:
    imExecutionRequestUnitary:
      description: "the IM Execution Request Unitary"
      type: object
      required:
        - requestId
        - campaignId
        - recipients
      properties:
        requestId:
          type: string
          description: "the Unique Request Identifier"
          example: "request-12345"
        campaignId:
          type: string
          description: "the Campaign Identifier"
          example: "campaign-12345"
        recipients:
          $ref: '#/components/schemas/recipients'

    imExecutionRequestHighThroughput:
      description: "the IM Execution Request Unitary High Throughput"
      type: object
      required:
        - requestId
        - campaignId
        - recipients
      properties:
        requestId:
          type: string
          description: "the Unique Request Identifier"
          example: "request-12345"
        campaignId:
          type: string
          description: "the Campaign Identifier"
          example: "campaign-12345"
        recipients:
          type: array
          description: "the list of recipients"
          items:
            oneOf:
              - $ref: "#/components/schemas/ExternalRecipient"
            discriminator:
              propertyName: type
              mapping:
                external: "#/components/schemas/ExternalRecipient"
          minItems: 1
          maxItems: 20

    imExecutionRequestAudience:
      description: "the IM Execution Request Audience"
      type: object
      required:
        - campaignId
      properties:
        requestId:
          type: string
          description: "the Unique Request Identifier"
          example: "request-12345"
        campaignId:
          type: string
          description: "the Campaign Identifier"
          example: "campaign-12345"
        audience:
          $ref: '#/components/schemas/Audience'
        context:
          $ref: "#/components/schemas/context"
        schedule:
          $ref: "#/components/schemas/schedule"

    imExecutionResponse:
      description: "the execution response"
      type: object
      properties:
        executionId:
          description: "the execution ID"
          type: string
          example: "HUMA-00859153"
        requestId:
          description: "the request ID"
          type: string
          example: "REQ-80940549"
        createdAt:
          type: string
          format: date-time
          description: "the message execution creation time"
          example: "2016-08-29T09:12:33.001Z"
        createdBy:
          description: "the message execution creation user"
          type: string
          example: "5d1281e6d935456i4273@AdobeId"
        # modification details can be removed after addressing Auditable dependency
        modifiedAt:
          type: string
          format: date-time
          description: "the message execution modification time"
          example: '2016-08-29T09:12:33.001Z'
        modifiedBy:
          description: "the message execution modification user"
          type: string
          example: '4c0190e5d702748f0931@AdobeId'

    errorResponse:
      description: "the error response"
      type: object
      properties:
        type:
          type: string
          description: "the error type"
          example: "https://ns.adobe.com/aep/errors/MSG-000052-400"
        title:
          type: string
          description: "the error title"
          example: "An error has occurred"
        status:
          description: "the error status"
          type: integer
          example: 400
        report:
          description: "the error report"
          type: object
          properties:
            additionalContext:
              additionalProperties:
                type: string
          required:
            - additionalContext
          example:
            "additionalContext": {
              "requestId": "04e7a2a5-f6db-4d15-a1ba-edda77bdb66f",
              "campaignId": "campaign-1234567"
            }

    recipients:
      type: array
      description: "the list of recipients"
      items:
        oneOf:
          - $ref: "#/components/schemas/AEPRecipient"
          - $ref: "#/components/schemas/ExternalRecipient"
        discriminator:
          propertyName: type
          mapping:
            aep: "#/components/schemas/AEPRecipient"
            external: "#/components/schemas/ExternalRecipient"
      minItems: 1
      maxItems: 20

    Audience:
      type: object
      description: "Details of the AEP Audience "
      required:
        - id
      properties:
        id:
          type: string
          description: "Represents either audience or segment id"
          example: "AEP-ProfileID-12345"

    AEPRecipient:
      type: object
      description: "the AEP Recipient Information"
      required:
        - type
        - userId
        - namespace
      properties:
        type:
          type: string
          description: "recipient type: aep"
          example: "aep"
        userId:
          type: string
          description: "the AEP Profile identifier"
          example: "AEP-ProfileID-12345"
        namespace:
          type: string
          description: "the AEP Profile namespace"
          example: "email"
        mergePolicyName:
          type: string
          description: "Merge Policy Name"
          example: "Default Timebased"
        mergePolicySchema:
          type: string
          description: "Merge Policy Schema"
          example: "_xdm.context.profile"
        channelData:
          $ref: "#/components/schemas/recipientChannelData"
        profile:
          $ref: "#/components/schemas/profile"
        context:
          $ref: "#/components/schemas/context"
        attachments:
          $ref: "#/components/schemas/personalizedAttachments"

    ExternalRecipient:
      type: object
      description: "External Recipient Information"
      required:
        - type
        - userId
        - namespace
      properties:
        type:
          type: string
          description: "recipient type: external"
          example: "external"
        userId:
          type: string
          description: "External profile identifier, usually same as emailId or phoneNumber"
          example: "customer123@example.com"
        namespace:
          type: string
          description: "the AEP Profile namespace"
          example: "email"
        channelData:
          $ref: "#/components/schemas/recipientChannelData"
        profile:
          $ref: "#/components/schemas/profile"
        context:
          $ref: "#/components/schemas/context"
        attachments:
          $ref: "#/components/schemas/personalizedAttachments"

    personalizedAttachments:
      type: array
      description: "Personalized PDF attachments for this email recipient. A rendered email can contain at most five attachments. Combined attachment size is limited to 5 MB by default, or 10 MB if your organization has the applicable attachment size add-on. These limits include any static attachments authored in the campaign. Attachment validation occurs before the request is accepted; one invalid attachment rejects the entire request."
      minItems: 1
      maxItems: 5
      items:
        $ref: "#/components/schemas/personalizedAttachment"

    personalizedAttachment:
      type: object
      description: "A PDF attachment stored in the Adobe Experience Platform Data Landing Zone associated with the request sandbox."
      required:
        - name
        - contentType
        - source
      properties:
        name:
          type: string
          description: "The filename displayed by the email client. It must end in .pdf and cannot contain path separators, parent-directory references, or control characters."
          example: "invoice.pdf"
        contentType:
          type: string
          description: "The attachment MIME type. Only PDF attachments are supported."
          enum:
            - application/pdf
          example: "application/pdf"
        source:
          $ref: "#/components/schemas/dlzAttachmentSource"

    dlzAttachmentSource:
      type: object
      description: "Identifies an existing object in the Adobe Experience Platform Data Landing Zone."
      required:
        - type
        - path
      properties:
        type:
          type: string
          description: "The attachment source type."
          enum:
            - dlzPath
          example: "dlzPath"
        path:
          type: string
          description: "The non-empty Data Landing Zone object path. Do not include credentials, backslashes, empty path segments, or current/parent-directory segments."
          example: "personalized-attachments/campaign-12345/customer-123/invoice.pdf"

    recipientChannelData:
      type: object
      description: "the Channel Data for recipient , Its an Optional Field for type aep"
      properties:
        emailAddress:
          type: string
          description: "the email address for emailing which also doubles up as the external userId"
          example: "customer123@example.com"
        mobilePhoneNumber:
          type: string
          description: "the mobile phone number for sms"
          example: "111-111-1111"
    profile:
      type: object
      description: "the profile data used for dynamic variable substitution in message content"
      additionalProperties:
        oneOf:
          - type: string
          - type: object
      example:
        {
          "person": { "name": { "firstName": "Jane", "lastName": "Doe" } }
        }
        # Multiple examples support is not available in the currently used OpenAPI version
        # So showing additional examples as comments
        # Example 2: Simple string properties
      # "mobilePhone": {
      #   "primary": "111-111-1111"
      # }
    context:
      type: object
      description: "the context data used for dynamic variable substitution in message content"
      additionalProperties:
        oneOf:
          - type: string
          - type: object
      example:
        {
          "product": "Gaming Laptop"
        }
        # Multiple examples support is not available in the currently used OpenAPI version
        # So showing additional examples as comments
        # Example 2: Simple string properties
      # {
      #   "productName": "LED TV",
      #   "productCategory": "Electronics"
      # }
    schedule:
      type: object
      description: "The time at which campaign execution should be triggered"
      properties:
        executeAt:
          type: string
          format: date-time
          description: "the time of execution trigger"
          example: "2016-08-29T09:12:33.001Z"
    executionStatusResponse:
      type: object
      description: "Execution Status Response"
      required:
        - executionId
        - status
        - createdAt
      properties:
        executionId:
          type: string
          description: "executionId"
          example: "CMA-09378831"
        campaignId:
          type: string
          description: "campaignId"
          example: "campaignId-12345"
        audienceId:
          type: string
          description: "audienceId"
          example: "audienceId-12345"
        status:
          type: string
          description: "execution status"
          enum:
            - Succeeded
            - InProgress
            - Failed
          example: "Succeeded"
        targetedProfileCount:
          type: integer
          description: "number of profiles exported"
          example: "2"
        createdAt:
          type: string
          format: date-time
          example: '2016-08-29T09:12:33.001Z'

    ScheduledExecutionResponse:
      type: object
      description: "Scheduled Execution Response for scheduling or status check of scheduled execution"
      required:
        - scheduleId
        - scheduleStatus
      properties:
        scheduleId:
          type: string
          description: "scheduleId"
          example: "schedule-id-123"
        audience:
          $ref: "#/components/schemas/Audience"
        campaignId:
          type: string
          description: "campaignId"
          example: "campaignId-12345"
        executeAt:
          type: string
          format: date-time
          description: "the time of execution trigger"
          example: "2016-08-29T09:12:33.001Z"
        scheduleStatus:
          type: string
          description: "schedule status"
          enum:
            - Scheduled
            - Triggered
          example: "Scheduled"
        executionDetails:
          $ref: "#/components/schemas/executionStatusResponse"