openapi: 3.0.2
info:
  title: Message API
  version: 1.0.0
  description: |
    Send and receive email messages via your epilot organization
security:
- EpilotAuth: []
- EpilotOrg: []
tags:
- name: Messages
- name: Threads
- name: Drafts
- name: message_schema
  x-displayName: Message
  description: |
    <SchemaDefinition schemaRef="#/components/schemas/Message" />
- name: thread_schema
  x-displayName: Thread
  description: |
    <SchemaDefinition schemaRef="#/components/schemas/Thread" />
x-tagGroups:
- name: APIs
  tags:
  - Messages
  - Threads
  - Drafts
- name: Schemas
  tags:
  - message_schema
  - thread_schema
paths:
  /v1/message/messages:
    post:
      operationId: sendMessage
      summary: sendMessage
      description: Send an email message
      tags:
      - Messages
      parameters:
      - in: query
        name: do_not_create_entities
        description: When true, this flag lets the caller to send only the message and by-pass creating the thread & message entities.
        schema:
          default: false
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequestParams'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageRequestParams'
        '403':
          description: Forbidden
    put:
      operationId: updateMessage
      summary: updateMessage
      description: Update message metadata
      tags:
      - Messages
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseEntity'
                - $ref: '#/components/schemas/Message'
        '403':
          description: Forbidden
  /v1/message/messages/{id}:
    get:
      operationId: getMessage
      summary: getMessage
      description: Get an email message by id
      tags:
      - Messages
      parameters:
      - name: id
        description: Message ID
        in: path
        required: true
        schema:
          type: string
          example: 4d74976d-fb64-47fd-85e2-65eea140f5eb
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseEntity'
                - $ref: '#/components/schemas/Message'
        '302':
          description: Redirect to V2 API to fetch the download URL
          headers:
            Location:
              description: V2 API
              schema:
                type: string
                example: https://message.sls.epilot.io/v2/messages/4d74976d-fb64-47fd-85e2-65eea140f5eb
        '403':
          description: Forbidden
    delete:
      operationId: deleteMessage
      summary: deleteMessage
      description: Immediately and permanently delete a message. This operation cannot be undone.
      tags:
      - Messages
      parameters:
      - name: id
        description: Message ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden
  /v1/message/messages/{id}/trash:
    post:
      operationId: trashMessage
      summary: trashMessage
      description: Move a message to the trash
      tags:
      - Messages
      parameters:
      - name: id
        description: Message ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden
  /v1/message/messages/{id}/untrash:
    post:
      operationId: untrashMessage
      summary: untrashMessage
      description: Restore a trashed message
      tags:
      - Messages
      parameters:
      - name: id
        description: Message ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden
  /v1/message/messages/{id}/read:
    post:
      operationId: markReadMessage
      summary: markReadMessage
      description: Mark message as read
      tags:
      - Messages
      parameters:
      - name: id
        description: Message ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden
  /v2/message/messages/{id}/read:
    post:
      operationId: markReadMessageV2
      summary: markReadMessageV2
      description: Mark message as read within a scope
      tags:
      - Messages
      parameters:
      - name: id
        description: Message ID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadMessagePayload'
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden
  /v1/message/messages/{id}/unread:
    post:
      operationId: markUnreadMessage
      summary: markUnreadMessage
      description: Mark message as unread
      tags:
      - Messages
      parameters:
      - name: id
        description: Message ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden
  /v2/message/messages/{id}/unread:
    post:
      operationId: markUnreadMessageV2
      summary: markUnreadMessageV2
      description: Mark message as unread within a scope
      tags:
      - Messages
      parameters:
      - name: id
        description: Message ID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadMessagePayload'
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads:search:
    post:
      operationId: searchThreads
      summary: searchThreads
      description: |
        Search for threads of email messages.

        Messages with no replies yet are treated as threads with single message.

        Lucene syntax supported.
      tags:
      - Threads
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - hits
                - results
                properties:
                  hits:
                    type: number
                    description: Total of matched threads
                    example: 14
                  results:
                    type: array
                    description: Matched threads
                    items:
                      allOf:
                      - $ref: '#/components/schemas/BaseEntity'
                      - $ref: '#/components/schemas/Thread'
        '403':
          description: Forbidden
  /v2/message/threads:search:
    post:
      operationId: searchThreadsV2
      summary: searchThreadsV2
      description: |
        Search for threads of email messages.

        Messages with no replies yet are treated as threads with single message.

        Lucene syntax supported.
      tags:
      - Threads
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchParamsV2'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - hits
                - results
                properties:
                  hits:
                    type: number
                    description: Total of matched threads
                    example: 14
                  results:
                    type: array
                    description: Matched threads
                    items:
                      allOf:
                      - $ref: '#/components/schemas/BaseEntity'
                      - $ref: '#/components/schemas/Thread'
        '403':
          description: Forbidden
  /v1/message/threads:searchIds:
    post:
      operationId: searchIds
      summary: Search threads and return all id's
      description: |
        Return all thread id's that match a criteria

        Lucene syntax supported.
      tags:
      - Threads
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchIDParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - hits
                - results
                properties:
                  hits:
                    type: number
                    description: Total of matched threads
                    example: 14
                  results:
                    type: array
                    description: Matched threads ids
                    items:
                      type: string
        '403':
          description: Forbidden
  /v1/message/threads:
    put:
      operationId: updateThread
      summary: updateThread
      description: Modify thread metadata
      tags:
      - Threads
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseEntity'
                - $ref: '#/components/schemas/Thread'
        '403':
          description: Forbidden
  /v1/message/threads/{id}:
    delete:
      operationId: deleteThread
      summary: deleteThread
      description: Immediately and permanently delete a thread. This operation cannot be undone.
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/{id}:markAsDone:
    post:
      operationId: markThreadAsDone
      summary: markThreadAsDone
      description: Mark thread as done
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success
        '400':
          description: Bad Request
  /v1/message/threads/{id}:markAsOpen:
    post:
      operationId: markThreadAsOpen
      summary: markThreadAsOpen
      description: Mark thread as open
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success
        '400':
          description: Bad Request
  /v1/message/threads/{id}/timeline:
    get:
      operationId: getThreadTimeline
      summary: getThreadTimeline
      description: Get thread timeline
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadTimeline'
        '403':
          description: Forbidden
  /v1/message/threads/{id}/trash:
    post:
      operationId: trashThread
      summary: trashThread
      description: Move a thread to trash
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/{id}/untrash:
    post:
      operationId: untrashThread
      summary: untrashThread
      description: Restore a trashed thread
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/bulk:read:
    post:
      operationId: threadBulkActionsRead
      summary: threadBulkActionsRead
      description: Perform a bulk action of marking an array of thread ids as read
      tags:
      - Threads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkActionsPayloadWithScopes'
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/bulk:unread:
    post:
      operationId: threadBulkActionsUnread
      summary: threadBulkActionsUnread
      description: Perform a bulk action of marking an array of thread ids as unread
      tags:
      - Threads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkActionsPayloadWithScopes'
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/bulk:favorite:
    post:
      operationId: threadBulkActionsFavorite
      summary: threadBulkActionsFavorite
      description: Perform a bulk action of marking an array of thread ids favorite
      tags:
      - Threads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkActionsPayload'
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/bulk:unfavorite:
    post:
      operationId: threadBulkActionsUnfavorite
      summary: threadBulkActionsUnfavorite
      description: Perform a bulk action of marking an array of thread ids unfavorited
      tags:
      - Threads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkActionsPayload'
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/bulk:trash:
    post:
      operationId: threadBulkActionsTrash
      summary: threadBulkActionsTrash
      description: Perform a bulk action of trashing an array of threads
      tags:
      - Threads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkActionsPayload'
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/bulk:untrash:
    post:
      operationId: threadBulkActionsUntrash
      summary: threadBulkActionsUntrash
      description: Perform a bulk action of untrashing an array of threads
      tags:
      - Threads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkActionsPayload'
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/bulk:delete:
    post:
      operationId: threadBulkActionsDelete
      summary: threadBulkActionsDelete
      description: Performs a bulk permanent delete for all threads
      tags:
      - Threads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkActionsPayload'
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/bulk:done:
    post:
      operationId: threadBulkActionsDone
      summary: threadBulkActionsDone
      description: Perform a bulk action of marking an array of threads as done
      tags:
      - Threads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkActionsPayload'
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/bulk:open:
    post:
      operationId: threadBulkActionsOpen
      summary: threadBulkActionsOpen
      description: Perform a bulk action of marking an array of threads as open
      tags:
      - Threads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkActionsPayload'
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/{id}/read:
    post:
      operationId: markReadThread
      summary: markReadThread
      description: Mark thread as read
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v2/message/threads/{id}/read:
    post:
      operationId: markReadThreadV2
      summary: markReadThreadV2
      description: Mark thread as read within a scope
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadMessagePayload'
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/{id}/unread:
    post:
      operationId: markUnreadThread
      summary: markUnreadThread
      description: Mark thread as unread
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v2/message/threads/{id}/unread:
    post:
      operationId: markUnreadThreadV2
      summary: markUnreadThreadV2
      description: Mark thread as unread within a scope
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadMessagePayload'
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/{id}/assign:
    post:
      operationId: assignThread
      summary: assignThread
      description: Assign thread to entities
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Entities which thread is assigned to
              type: array
              items:
                type: object
                properties:
                  slug:
                    description: Entity slug
                    type: string
                    example: contact
                  entity_id:
                    description: Entity ID
                    type: string
                    example: 3f34ce73-089c-4d45-a5ee-c161234e41c3
                  org_id:
                    description: Organization ID
                    type: string
                    example: '206801'
                  is_main_entity:
                    description: To indicate this is main entity
                    type: boolean
                    example: true
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/{id}/unassign:
    post:
      operationId: unassignThread
      summary: unassignThread
      description: Unassign thread from entities
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Entities which thread is unassigned from
              type: array
              items:
                type: object
                properties:
                  slug:
                    description: Entity slug
                    type: string
                    example: contact
                  entity_id:
                    description: Entity ID
                    type: string
                    example: 3f34ce73-089c-4d45-a5ee-c161234e41c3
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/{id}/assign:users:
    post:
      operationId: assignUsers
      summary: assignUsers
      description: |
        Assign users to thread for receiving notifications.
        The operation replaces all existing assigned users in thread.
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: User IDs of users assigned to thread
              type: object
              properties:
                assigned_to:
                  type: array
                  description: IDs of users assigned to thread
                  items:
                    type: string
                    example: '206801'
      responses:
        '204':
          description: Success
        '403':
          description: Forbidden
  /v1/message/threads/{id}:pin:
    post:
      operationId: pinThread
      summary: Pin a single thread
      description: Pin a single thread
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success
        '400':
          description: Bad request
        '404':
          description: Thread not found
        '409':
          description: Concurrent update error
        '500':
          description: Internal server error
    delete:
      operationId: unpinThread
      summary: Unpin a single thread
      description: Unpin a single thread
      tags:
      - Threads
      parameters:
      - name: id
        description: Thread ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success
        '400':
          description: Bad request
        '404':
          description: Thread not found
        '409':
          description: Concurrent update error
        '500':
          description: Internal server error
  /v1/message/drafts:
    post:
      operationId: createDraft
      summary: createDraft
      description: Create a new draft
      tags:
      - Drafts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequestParams'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseEntity'
                - $ref: '#/components/schemas/Message'
        '403':
          description: Forbidden
  /v1/message/drafts:send:
    post:
      operationId: sendDraft
      summary: sendDraft
      description: Send the existing draft to the recipients
      tags:
      - Drafts
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseEntity'
                - $ref: '#/components/schemas/Message'
        '403':
          description: Forbidden
  /v2/message/messages/{id}:
    get:
      operationId: getMessageV2
      summary: getMessageV2
      description: |
        - Fetches message by ID
        - If the message html is omitted on the entity, then it keeps the content on the message as a signed url
          {
            ...
            _id: "4d74976d-fb64-47fd-85e2-65eea140f5eb",
            _schema: "message",
            _org: "org-123",
            html_omitted: true,
            html_download_url: "https://s3.eu-central-1.amazonaws.com/epilot-attachments/3f34ce73-089c-4d45-a5ee-c161234e41c3/3f34ce73-089c-4d45-a5ee-c161234e41c3.html"
          }
      tags:
      - Messages
      parameters:
      - name: id
        description: Message ID
        in: path
        required: true
        schema:
          type: string
          example: 4d74976d-fb64-47fd-85e2-65eea140f5eb
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/MessageV2'
        '403':
          description: Forbidden
components:
  securitySchemes:
    EpilotAuth:
      type: http
      scheme: bearer
      description: Authorization header with epilot OAuth2 bearer token
      bearerFormat: JWT
    EpilotOrg:
      description: Overrides the target organization to allow shared tenant access
      name: x-epilot-org-id
      in: header
      type: apiKey
  schemas:
    BaseEntity:
      type: object
      required:
      - _id
      - _title
      - _org
      - _schema
      - _created_at
      - _updated_at
      properties:
        _id:
          type: string
          description: Entity ID
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        _title:
          type: string
          description: Entity title
        _org:
          type: string
          description: Organization ID the entity belongs to
          example: '206801'
        _schema:
          type: string
          description: URL-friendly identifier for the entity schema
          example: message
        _tags:
          type: array
          description: Entity tags
          items:
            type: string
          example:
          - pricing
          - INBOX
        _created_at:
          type: string
          description: Created date
          format: date-time
          example: 2021-02-09T12:41:43.662Z
        _updated_at:
          type: string
          description: Updated date
          format: date-time
          example: 2021-02-10T09:14:31.990Z
    Thread:
      description: Thread properties depend on API caller as it's not pre-defined. We do recommend having at least `topic` property for categorizing.
      required:
      - topic
      properties:
        topic:
          type: string
          description: Message topic (e.g. which service sends the message or message category)
          example: CUSTOMER_MESSAGE
        assigned_to:
          type: array
          description: User ID of who the message is assigned to. Default is the user who sends message.
          items:
            type: string
            example:
            - '206801'
            - '200109'
        org_read_message:
          type: array
          description: Organization ID of organization read the message.
          items:
            type: string
            example:
            - '789372'
            - '210291'
        done:
          type: boolean
          description: Whether the thread is marked as Done
          example: false
        latest_message:
          type: object
          description: Latest message of thread
          $ref: '#/components/schemas/Message'
        latest_trash_message:
          type: object
          description: Latest trash message of thread
          $ref: '#/components/schemas/Message'
        latest_message_at:
          type: string
          description: The date of the latest message time in the thread
          example: 2024-02-10T09:14:31.990Z
    Message:
      type: object
      required:
      - subject
      - from
      properties:
        message_id:
          type: string
          description: Message ID which is from email provider. If you provide `message-id`, API overrides by its own value.
          example: <0102017b97a502f8-a67f01c2-68cc-4928-b91b-45853f34e259-000000@eu-west-1.amazonses.com>
        sender:
          type: string
          description: User ID of user sends the message.
          example: '206801'
        subject:
          type: string
          description: Subject
          example: Request for solar panel price
        html:
          type: string
          description: HTML body
          example: <div>We at ABC GmbH would like to request a price quote for the solar panel.</div>
        text:
          type: string
          description: Text body
          example: We at ABC GmbH would like to request a price quote for the solar panel.
        from:
          $ref: '#/components/schemas/Address'
        reply_to:
          $ref: '#/components/schemas/Address'
        to:
          type: array
          description: To email addresses
          items:
            $ref: '#/components/schemas/Address'
        cc:
          type: array
          description: Cc email addresses
          items:
            $ref: '#/components/schemas/Address'
        bcc:
          type: array
          description: Bcc email addresses
          items:
            $ref: '#/components/schemas/Address'
        file:
          $ref: '#/components/schemas/AttachmentsRelation'
        references:
          type: string
          description: >
            References header. Value is the series of `message_id` which is reparated by space to indicate that message has parent.            The last message ID in references identifies the parent. The first message ID in references
            identifies the first message in the thread.            The basic idea is that sender should copy `references` from the parent and append the parent's `message_id` when replying.
          example: <0102017b97a502f8-a67f01c2-68cc-4928-b91b-45853f34e259-000000@eu-west-1.amazonses.com> <CALHgQpziyxW9NaFUs+nRMykzr6Ljq6vjq4WO9SaihAuMasuDyg@mail.gmail.com>
        in_reply_to:
          type: string
          description: |
            In-Reply-To header. Value is the `message_id` of parent message.
          example: <CALHgQpziyxW9NaFUs+nRMykzr6Ljq6vjq4WO9SaihAuMasuDyg@mail.gmail.com>
        user_read_message:
          type: array
          description: User ID of user read the message.
          items:
            type: string
            example:
            - '206801'
            - '200109'
        org_read_message:
          type: array
          description: Organization ID of organization read the message.
          items:
            type: string
            example:
            - '789372'
            - '210291'
        send_status:
          type: array
          description: >
            Sent message status. The array contains sending message status corresponding to all recipients. For more detail, check `send_status` of each recipient in `to`, `cc`, `bcc`            Reference at
            <https://docs.aws.amazon.com/ses/latest/DeveloperGuide/monitor-sending-activity.html>
          items:
            type: string
            enum:
            - SEND
            - DELIVERY
            - REJECT
            - COMPLAINT
            - BOUNCE
            - ERROR
        type:
          type: string
          description: Message type
          enum:
          - SENT
          - RECEIVED
        template_id:
          type: string
          description: Template ID used for sending message.
          example: 3f34ce73-089c-4d45-a5ee-c161234e41c3
    MessageV2:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - $ref: '#/components/schemas/Message'
      properties:
        html_omitted:
          type: boolean
          description: If true then html is not provided and must be downloaded using the html_download_url
          default: false
        html_download_url:
          type: string
          description: HTML body download URL
          example: https://s3.eu-central-1.amazonaws.com/epilot-attachments/3f34ce73-089c-4d45-a5ee-c161234e41c3/3f34ce73-089c-4d45-a5ee-c161234e41c3.html
    Address:
      type: object
      required:
      - address
      properties:
        name:
          type: string
          description: Email address alias
          example: epilot
        address:
          type: string
          description: Email address
          example: messaging@epilot.cloud
        email_type:
          type: string
          description: |
            Type of the email, Internal (360 Agents), Partners, External users(Customers)
          nullable: true
          enum:
          - INTERNAL
          - EXTERNAL
          - PARTNER
        send_status:
          type: string
          description: |
            Sent message status regarding to this recipient.            Reference at <https://docs.aws.amazon.com/ses/latest/DeveloperGuide/monitor-sending-activity.html>
          enum:
          - SEND
          - DELIVERY
          - REJECT
          - COMPLAINT
          - BOUNCE
          - ERROR
        send_error:
          type: object
          description: >
            Information about reject, complaint or bounce event. Only available if `send_status` is REJECT, COMPLAINT, BOUNCE or ERROR.            JSON object is defined by AWS SES. Reference at
            <https://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html>
    AttachmentsRelation:
      type: object
      description: Message attachments
      properties:
        $relation:
          type: array
          description: It's normal entity relation with some additional properties for sending message attachment.
          items:
            $ref: '#/components/schemas/File'
    File:
      type: object
      required:
      - entity_id
      properties:
        entity_id:
          type: string
          description: File entity ID
          example: f820ce3b-07b0-45ae-bcc6-babb2f53f79f
        filename:
          type: string
          description: File name
          example: Produktinformationen_epilot360_Double_Opt_in.pdf
        is_message_attachment:
          type: boolean
          description: To indicate this file relation is message attachment. If false then this file will not be sent and simply kept as a file relation.
        may_be_signature_attachment:
          type: boolean
          description: To indicate this file relation may be signature attachment. If true then this file will be sent as signature attachment and not related to any entity.
        cid:
          type: string
          description: Content ID (for inline)
          example: fb222496-a1a5-4639-94f2-07b5e35e4068
        inline:
          type: boolean
          description: |
            If true then this attachment should not be offered for download (at least not in the main attachments list).            The usecase is CID embedded image (aka inline image).
          default: false
        send_as_link:
          type: boolean
          description: |
            If true then this attachment is sent via link. The link have to be inserted to email body by API caller.            In this case, service doesn't process this attachment.
          default: false
    MessageRequestParams:
      required:
      - subject
      - from
      additionalProperties: true
      properties:
        thread:
          type: object
          required:
          - topic
          description: >
            Open new thread when sending the very first message in conversation. Thread should contains context related to all messages in it (eg. topic, brand_id, opportunity_id, assigned_to,...).            Thread properties depend on API
            caller as it's not pre-defined. We do recommend having at least `topic` property for categorizing.            `thread` or `parent_id` must be provided either.
          properties:
            topic:
              type: string
              description: Message topic (e.g. which service sends the message or message category)
            assigned_to:
              type: array
              description: User ID of who the message is assigned to. Default is the user who sends message.
              items:
                type: string
          example:
            topic: CUSTOMER_MESSAGE
            assigned_to:
            - '206801'
            - '200109'
            opportunity_id: 829072
        parent_id:
          type: string
          description: |
            Entity ID of parent message which this message replies to or forwards from.            If both `parent_id` and `thread` are provided, `thread` is discarded.
          example: 44d7a3eb-0cce-4bd3-a7cd-0b3e652de0c2
        subject:
          type: string
          description: Subject
          example: Request for solar panel price
        html:
          type: string
          description: HTML body
          example: <div>We at ABC GmbH would like to request a price quote for the solar panel.</div>
        text:
          type: string
          description: Text body. If not provided, text body is converted from HTML body using [html-to-text](https://www.npmjs.com/package/html-to-text)
          example: We at ABC GmbH would like to request a price quote for the solar panel.
        from:
          $ref: '#/components/schemas/Address'
        reply_to:
          $ref: '#/components/schemas/Address'
        to:
          type: array
          description: To email addresses
          items:
            $ref: '#/components/schemas/Address'
        cc:
          type: array
          description: Cc email addresses
          items:
            $ref: '#/components/schemas/Address'
        bcc:
          type: array
          description: Bcc email addresses
          items:
            $ref: '#/components/schemas/Address'
        file:
          $ref: '#/components/schemas/AttachmentsRelation'
        template_id:
          type: string
          description: Template ID used for sending message.
          example: 3f34ce73-089c-4d45-a5ee-c161234e41c3
    SearchParamsV2:
      type: object
      required:
      - q
      properties:
        q:
          description: Lucene query syntax supported with ElasticSearch
          type: string
          example: subject:"Request for solar panel price" AND _tags:INBOX
        fields:
          description: List of entity fields to include in results
          schema:
            $ref: '#/components/schemas/FieldsParam'
        from:
          type: integer
          minimum: 0
          default: 0
        size:
          type: integer
          minimum: 1
          default: 10
        hydrate:
          type: boolean
          default: false
        include_scores:
          type: boolean
          default: false
        sort:
          type: string
        highlight: {}
    SearchParams:
      type: object
      required:
      - q
      properties:
        q:
          description: Lucene query syntax supported with ElasticSearch
          type: string
          example: subject:"Request for solar panel price" AND _tags:INBOX
        from:
          type: integer
          minimum: 0
          default: 0
        size:
          type: integer
          minimum: 1
          default: 10
        hydrate:
          type: boolean
          default: false
    SearchIDParams:
      type: object
      properties:
        q:
          description: Lucene query syntax supported with ElasticSearch
          type: string
          example: subject:"Request for solar panel price" AND _tags:INBOX
    ReadMessagePayload:
      type: object
      required:
      - scopes
      properties:
        scopes:
          description: The scopes to be used when marking an item as read or unread. The read status will be synced for all provided scopes.
          example:
          - organization
          - user
          type: array
          default:
          - organization
          - user
          items:
            $ref: '#/components/schemas/ReadingScope'
    ReadingScope:
      description: Who is marking an item as read or unread.
      type: string
      enum:
      - organization
      - user
    ThreadTimeline:
      type: object
      required:
      - events
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/TimelineEvent'
    ThreadDoneEvent:
      type: object
      required:
      - type
      - user_id
      - organization_id
      properties:
        type:
          type: string
          enum:
          - THREAD_DONE
        user_id:
          type: string
          description: User ID of the user who marked the thread as done
          example: 123
        organization_id:
          type: string
          description: Organization ID of the organization who marked the thread as done
          example: 456
    ThreadOpenEvent:
      type: object
      required:
      - type
      - user_id
      - organization_id
      properties:
        type:
          type: string
          enum:
          - THREAD_OPEN
        user_id:
          type: string
          description: User ID of the user who marked the thread as open
          example: 123
        organization_id:
          type: string
          description: Organization ID of the organization who marked the thread as open
          example: 456
    TimelineEventData:
      type: object
      discriminator:
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/ThreadDoneEvent'
      - $ref: '#/components/schemas/ThreadOpenEvent'
    TimelineEvent:
      type: object
      required:
      - timestamp
      - data
      properties:
        data:
          $ref: '#/components/schemas/TimelineEventData'
        timestamp:
          type: string
          description: Timestamp of the event
          example: 2024-01-01T00:00:00.000Z
    BulkActionsPayloadWithScopes:
      allOf:
      - $ref: '#/components/schemas/BulkActionsPayload'
      - type: object
        properties:
          scopes:
            description: The scopes to be used when marking an item as read or unread. The read status will be synced for all provided scopes.
            example:
            - organization
            - user
            type: array
            default:
            - organization
            - user
            items:
              $ref: '#/components/schemas/ReadingScope'
    BulkActionsPayload:
      type: object
      required:
      - ids
      properties:
        ids:
          description: Array of threads you wish to perform bulk actions on
          example:
          - 6b299eda-4018-4554-8965-c4b5598e6531
          type: array
          items:
            type: string
    FieldsParam:
      type: array
      description: |
        List of entity fields to include or exclude in the response

        Use ! to exclude fields, e.g. `!_id` to exclude the `_id` field.

        Globbing and globstart (**) is supported for nested fields.
      items:
        type: string
      example:
      - _id
      - _title
      - first_name
      - account
      - '!account.*._files'
      - '**._product'
servers:
- url: https://message.sls.epilot.io

