openapi: 3.0.2
info:
  title: Email template API
  version: 1.1.0
  description: |
    Email template API service
tags:
- name: Email templates
  description: Email template service
- name: Variables
  description: Variable service
- name: email_template_schema
  x-displayName: Email Template
  description: |
    <SchemaDefinition schemaRef="#/components/schemas/EmailTemplateEntity" />
x-tagGroups:
- name: APIs
  tags:
  - Email templates
  - Variables
- name: Schemas
  tags:
  - email_template_schema
security:
- EpilotAuth: []
- AsOrganization: []
- EpilotOrg: []
paths:
  /v1/email-template/templates:
    post:
      operationId: saveTemplate
      summary: saveTemplate
      description: Create or update a template. If `id` is provided, it will update the template.
      tags:
      - Email templates
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTemplateRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateEntity'
        '403':
          description: Forbidden
  /v1/email-template/templates/{id}:
    get:
      operationId: getTemplateDetail
      summary: getTemplateDetail
      description: Get email template by ID
      tags:
      - Email templates
      parameters:
      - name: id
        description: Template entity ID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateResponse'
        '403':
          description: Forbidden
        '404':
          description: Not found
    put:
      operationId: updateTemplateDetail
      summary: updateTemplateDetail
      description: Update email template by ID
      tags:
      - Email templates
      parameters:
      - name: id
        description: Template entity ID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTemplateRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateEntity'
        '403':
          description: Forbidden
        '404':
          description: Not found
  /v1/email-template/templates/{id}:migrate-automations:
    post:
      operationId: migrateAutomationsForTemplate
      summary: migrateAutomationsForTemplate
      description: |
        Find all automation flows in the org that contain a `send-email` or `reply-email`
        action referencing `old_template_id` and rewrite those actions to point at the
        new template id (`{id}` path param). Intended to be called after a duplicated
        template has been refined, so automations follow over to the new template.
      tags:
      - Email templates
      parameters:
      - name: id
        description: New template id (the duplicate that automations should be migrated onto)
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - old_template_id
              properties:
                old_template_id:
                  type: string
                  description: Source template id that automations are being migrated away from
                  example: 511ceb90-f738-47aa-8b1e-915ace0ae13c
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MigrateAutomationsResponse'
        '403':
          description: Forbidden
  /v1/email-template/templates/{id}:references:
    get:
      operationId: getTemplateReferences
      summary: getTemplateReferences
      description: |
        List the automation flows, workflows and customer portals that currently
        reference this template, without modifying anything. Powers the template
        settings "used by" view and the pre-migrate preview, and uses the same
        discovery as `migrateAutomationsForTemplate` so the preview matches what a
        migrate would touch.
      tags:
      - Email templates
      parameters:
      - name: id
        description: Template id to find references for
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateReferencesResponse'
        '403':
          description: Forbidden
  /v1/email-template/templates:replace:
    post:
      operationId: replaceVariables
      summary: replaceVariables
      description: Get template detail and replace all variables (template variables and document generation)
      deprecated: true
      tags:
      - Variables
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - email_template_id
              properties:
                email_template_id:
                  type: string
                  example: 511ceb90-f738-47aa-8b1e-915ace0ae13c
                variable_parameters:
                  $ref: '#/components/schemas/VariableParameters'
                must_include_unsubscribe_link:
                  type: boolean
                  description: |
                    If true then include unsubscribe link in the email body
                  default: false
                skip_document_generation:
                  type: boolean
                  description: |
                    If true then skip document generation. This is useful when you want to replace html variables only. Speeds up the process.
                  default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateResponse'
        '403':
          description: Forbidden
  /v1/email-template/templates:replaceAsync:
    post:
      operationId: replaceVariablesAsync
      summary: replaceVariablesAsync
      description: |
        This endpoint allows to initiate an asynchronous process in replacing the template details & generating the documents.
        On initial request, a jobId and STARTED status are returned. Subsequent requests can use this jobId to poll for the resolved template.
        If still processing, it returns the jobId and IN-PROGRESS status. Upon completion or failure, it returns the final template or a failure status with reason.
      tags:
      - Variables
      parameters:
      - in: query
        name: job_id
        description: Job ID for tracking the status of document generation action
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email_template_id:
                  type: string
                  example: 511ceb90-f738-47aa-8b1e-915ace0ae13c
                variable_parameters:
                  $ref: '#/components/schemas/VariableParameters'
                must_include_unsubscribe_link:
                  type: boolean
                  description: |
                    If true then include unsubscribe link in the email body
                  default: false
                skip_document_generation:
                  type: boolean
                  description: |
                    If true then skip document generation. This is useful when you want to replace html variables only. Speeds up the process.
                  default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncEmailTemplateResponse'
        '403':
          description: Forbidden
  /v1/email-template/templates:bulkSendMessage:
    post:
      operationId: bulkSendMessage
      summary: bulkSendMessage
      description: Send emails to multiple recipients using a template
      tags:
      - Email templates
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/BulkSendMessageRequestWithQuery'
              - $ref: '#/components/schemas/BulkSendMessageRequest'
              - type: object
                required:
                - job_id
                properties:
                  job_id:
                    type: string
                    description: Job ID for tracking the status of a bulk message request
                    example: 8c086140-f33e-4bb7-a993-50c0f2402c7b
                  action:
                    type: string
                    description: |
                      Trigger an APPROVE OR CANCEL action for the bulk message request.

                      * APPROVE: Alias for APPROVE_WITH_CONSENT
                      * APPROVE_WITH_CONSENT: Approve the bulk message request and send emails to queued recipients with consent
                      * APPROVE_ALL: Approve the bulk message request and send emails to all queued recipients, including those without consent
                      * CANCEL: Cancel the bulk message request
                    enum:
                    - APPROVE
                    - APPROVE_WITH_CONSENT
                    - APPROVE_ALL
                    - CANCEL
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSendMessageJob'
        '403':
          description: Forbidden
  /v1/email-template/templates:revert:
    post:
      operationId: revertToOriginalTemplate
      summary: revertToOriginalTemplate
      description: Revert to the original system generated email template
      tags:
      - Email templates
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - email_template_id
              properties:
                email_template_id:
                  type: string
                  example: 511ceb90-f738-47aa-8b1e-915ace0ae13c
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden
  /v1/email-template/templates/{id}:convertToBuilder:
    post:
      operationId: convertToBuilder
      summary: convertToBuilder
      description: |
        Converts a legacy HTML email template into the email-builder block format.
        Stores the new `json_template` (stringified block graph), re-renders `body`
        from the resulting blocks, and stashes the original HTML at `backup.body`.
        Returns 409 if the template is already converted unless `force=true`.
      tags:
      - Email templates
      parameters:
      - name: id
        description: Template entity ID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                dryRun:
                  type: boolean
                  description: When true, return the converted output without saving.
                  example: false
                force:
                  type: boolean
                  description: When true, overwrite an existing json_template.
                  example: false
                as_copy:
                  type: boolean
                  description: When true, leave the source template untouched and save the converted result as a NEW template (linked via original_template_id). The response is the new entity.
                  example: false
                name:
                  type: string
                  description: Optional name for the as_copy result. The UI sends a localized copy name (e.g. "Copy of <name> (Visual)") so the new template is named like the list-view "Duplicate" action. Ignored unless as_copy is true.
                  example: Copy of Welcome email (Visual)
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateEntity'
        '400':
          description: Template body is empty
        '403':
          description: Forbidden
        '404':
          description: Not found
        '409':
          description: Template already converted; pass force=true to overwrite
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: Ivy 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:
          - automatic email template
        _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
        _purpose:
          type: array
          description: Entity Purposes
          items:
            type: string
          example:
          - a0ec23ac-12f8-4d89-9a63-91cba3787f2a
          - 310cd388-2f15-4b5b-8f98-ca14c1e03304
        _manifest:
          type: array
          description: Manifest ID used to create/update the entity
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
    TemplateReferenceItem:
      type: object
      required:
      - id
      properties:
        id:
          type: string
        name:
          type: string
          nullable: true
          description: Human-friendly name (flow_name / workflow name / portal name); may be absent.
    TemplateReferencesResponse:
      type: object
      required:
      - flows
      - workflows
      - portals
      - portal_lookup_errored
      properties:
        flows:
          type: array
          description: Automation flows whose send-email/reply-email actions reference this template
          items:
            $ref: '#/components/schemas/TemplateReferenceItem'
        workflows:
          type: array
          description: v2 workflows that own a referencing automation flow
          items:
            $ref: '#/components/schemas/TemplateReferenceItem'
        portals:
          type: array
          description: Customer portals whose email-template config references this template
          items:
            $ref: '#/components/schemas/TemplateReferenceItem'
        portal_lookup_errored:
          type: boolean
          description: True when the customer-portal lookup failed, so `portals` may be incomplete.
    MigrateAutomationsResponse:
      type: object
      required:
      - migrated_flow_count
      - migrated_flow_ids
      - migrated_workflow_count
      - migrated_workflow_ids
      - migrated_portal_count
      - migrated_portal_ids
      - failed_flow_ids
      - failed_portal_ids
      - portal_migration_errored
      properties:
        migrated_flow_count:
          type: integer
          description: Number of automation flows successfully rewritten to point at the new template
          example: 3
        migrated_flow_ids:
          type: array
          description: IDs of automation flows that were successfully migrated
          items:
            type: string
        migrated_workflow_count:
          type: integer
          description: |
            Number of v2 workflows whose `AUTOMATION` tasks point at a migrated automation flow.
            Derived from `migrated_flow_ids` — a workflow is counted once even if multiple of
            its tasks reference the same migrated flow.
          example: 2
        migrated_workflow_ids:
          type: array
          description: IDs of workflows (`wf-*`) that owned at least one migrated automation flow
          items:
            type: string
        migrated_portal_count:
          type: integer
          description: |
            Number of customer-portal email-template config rows whose references were rewritten
            from the old template id to the new one (via customer-portal-api's
            `migrateEmailTemplateReferences`).
          example: 1
        migrated_portal_ids:
          type: array
          description: Portal IDs whose email-template references were successfully rewritten
          items:
            type: string
        failed_flow_ids:
          type: array
          description: IDs of automation flows whose `putFlow` update failed. Caller can retry or surface to the user.
          items:
            type: string
        failed_portal_ids:
          type: array
          description: Portal IDs whose email-template reference rewrite failed in customer-portal-api.
          items:
            type: string
        portal_migration_errored:
          type: boolean
          description: |
            True when the call to customer-portal-api threw before returning, so the portal
            counts could not be computed. Flow/workflow results are still valid; the caller
            should surface this and offer a retry of the portal migration.
          example: false
    EmailTemplateRequest:
      type: object
      required:
      - name
      - subject
      properties:
        _id:
          type: string
          example: cd7809ba-a111-4dd9-8d15-18eb4de0faed
        _tags:
          type: array
          description: Entity tags
          items:
            type: string
          example:
          - template
        _manifest:
          type: array
          description: Manifest ID used to create/update the entity
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
        _purpose:
          type: array
          description: Entity Purposes
          items:
            type: string
          example:
          - a0ec23ac-12f8-4d89-9a63-91cba3787f2a
          - 310cd388-2f15-4b5b-8f98-ca14c1e03304
        name:
          description: name
          type: string
          example: Order confirmation
        brand_id:
          description: Brand ID. Equal 0 if available for All brands
          type: number
          nullable: true
          example: 0
        from:
          description: From
          $ref: '#/components/schemas/From'
        to:
          description: To
          type: array
          items:
            $ref: '#/components/schemas/To'
        cc:
          description: Cc
          type: array
          items:
            $ref: '#/components/schemas/To'
        bcc:
          description: Bcc
          type: array
          items:
            $ref: '#/components/schemas/To'
        subject:
          description: Subject
          type: string
          example: We have received your order!
        body:
          description: Body
          type: string
          example: Hi Ms Ny Huynh, </br> Thank you for your order. We will contact you shortly
        attachments:
          type: array
          nullable: true
          description: Email template attachments
          items:
            $ref: '#/components/schemas/Attachment'
        file:
          type: object
          properties:
            $relation:
              type: array
              description: Entity tags
              items:
                type: object
        system_template:
          description: >
            If template is created by system (Double Opt-in, CMD invitation,...) then true, and some attributes can not be edited such as Name, To,...

            Remember to add default content of template to [system-template.ts](https://gitlab.com/e-pilot/product/email-templates/svc-email-templates-api/-/blob/main/lambda/HandlerFunction/src/enum/system-template.ts) enum for revert to
            original feature
          type: boolean
          example: false
        created_by:
          description: Created by
          type: string
          example: 1234
        updated_by:
          description: Updated by
          type: string
          example: 1234
        json_template:
          type: string
          description: This field is used to store JSON templates. If this field is populated, then the Body html is derived from the JSON.
        original_template_id:
          type: string
          nullable: true
          description: |
            Set on a duplicated template to point at its source template id.
            Cleared (set to null) after automations referencing the source have been
            migrated onto the new template via `migrateAutomationsForTemplate`.
          example: cd7809ba-a111-4dd9-8d15-18eb4de0faed
        backup:
          type: object
          description: Snapshot of the legacy template body, taken when migrating to the email-builder format.
          properties:
            body:
              type: string
              description: Original HTML body before conversion to email-builder blocks.
            backed_up_at:
              type: string
              description: ISO 8601 timestamp when the backup was created.
              example: '2026-05-13T10:00:00.000Z'
        converted_to_new_editor:
          type: boolean
          description: True after the template has been converted from legacy HTML to the new email-builder format. Used by the UI to expose the "Revert to legacy HTML" action.
          example: false
    EmailTemplateEntity:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - type: object
        required:
        - name
        properties:
          name:
            description: name
            type: string
            example: Order confirmation
          brand_id:
            description: Brand ID. Equal 0 if available for All brands
            type: number
            nullable: true
            example: 0
          from:
            description: From
            $ref: '#/components/schemas/From'
          to:
            description: To
            type: array
            items:
              $ref: '#/components/schemas/To'
          cc:
            description: Cc
            type: array
            items:
              $ref: '#/components/schemas/To'
          bcc:
            description: Bcc
            type: array
            items:
              $ref: '#/components/schemas/To'
          subject:
            description: Subject
            type: string
            example: We have received your order!
          body:
            description: Body
            type: string
            example: Hi Ms Ny Huynh, </br> Thank you for your order. We will contact you shortly
          attachments:
            type: array
            nullable: true
            description: Email template attachments
            items:
              $ref: '#/components/schemas/Attachment'
          file:
            type: object
            properties:
              $relation:
                type: array
                description: Entity tags
                items:
                  type: object
          created_by:
            description: Created by
            type: string
            example: 1234
          updated_by:
            description: Updated by
            type: string
            example: 1234
          json_template:
            type: string
            description: This field is used to store JSON templates. If this field is populated, then the Body html is derived from the JSON.
          backup:
            type: object
            description: Snapshot of the legacy template body, taken when migrating to the email-builder format.
            properties:
              body:
                type: string
                description: Original HTML body before conversion to email-builder blocks.
              backed_up_at:
                type: string
                description: ISO 8601 timestamp when the backup was created.
                example: '2026-05-13T10:00:00.000Z'
          converted_to_new_editor:
            type: boolean
            description: True after the template has been converted from legacy HTML to the new email-builder format. Used by the UI to expose the "Revert to legacy HTML" action.
            example: false
          system_template:
            description: |
              If template is created by system (Double Opt-in, CMD invitation,...) then true, and some attributes can not be edited such as Name, To,...
              Remember to add default content of template to system_template enum for revert to original feature
            type: boolean
            example: false
          original_template_id:
            type: string
            nullable: true
            description: |
              Set on a duplicated template to point at its source template id.
              Cleared after automations have been migrated via `migrateAutomationsForTemplate`.
            example: cd7809ba-a111-4dd9-8d15-18eb4de0faed
    Attachment:
      type: object
      nullable: true
      required:
      - filename
      - size
      - content_type
      - bucket
      - object_key
      properties:
        cid:
          type: string
          description: Attachment ID
          example: f820ce3b-07b0-45ae-bcc6-babb2f53f79f
        filename:
          type: string
          description: File name
          example: Produktinformationen_epilot360_Double_Opt_in.pdf
        size:
          type: number
          description: File size in bytes
          example: 451349
        content_type:
          type: string
          description: Content type
          example: application/pdf
        url:
          type: string
          description: URL to download the attachment.
          example: https://go.epilot.cloud/attachments/3e7c616a-3e89-4f92-b4c5-ea5ab140e3dd/Produktinformationen_epilot360_Double_Opt_in.pdf
        bucket:
          type: string
          description: S3 bucket where file is stored
          example: 893487340562-message-attachment
        object_key:
          type: string
          description: S3 object apiKey
          example: attachments/3e7c616a-3e89-4f92-b4c5-ea5ab140e3dd/Produktinformationen_epilot360_Double_Opt_in.pdf
        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 is already inserted to email body by API caller. In this case, service doesn't process this attachment.
          default: false
        type:
          type: string
          description: File type such as Document template, Document,... Use for replace variables on document template
          example: Document template
        copy_to_message:
          type: boolean
          description: If true then this attachment is copied to the message and replaces corresponding one
          default: true
    From:
      type: object
      required:
      - email
      properties:
        name:
          type: string
          example: epilot
        email:
          type: string
          example: no-reply@epilot.cloud
    To:
      type: object
      required:
      - email
      properties:
        name:
          type: string
          example: Ny Huynh
        email:
          type: string
          example: ny.huynh@axonactive.com
    PresignedRequest:
      type: object
      required:
      - id
      - filename
      - content_type
      properties:
        id:
          description: UUID
          type: string
          example: 8c086140-f33e-4bb7-a993-50c0f2402c7b
        filename:
          description: File name
          type: string
          example: order.pdf
        content_type:
          description: Content type
          type: string
          example: application/pdf
    PresignedResponse:
      type: object
      required:
      - download_url
      - upload_url
      properties:
        download_url:
          type: string
          description: URL to download the attachment. This URL is not accessible until attachment is uploaded successfully.
          example: https://go.epilot.cloud/attachments/3e7c616a-3e89-4f92-b4c5-ea5ab140e3dd/Produktinformationen_epilot360_Double_Opt_in.pdf
        upload_url:
          description: Post presigned URL to upload file
          type: object
          required:
          - url
          - fields
          properties:
            url:
              type: number
              description: URL to upload the attachment
              example: https://s3.eu-central-1.amazonaws.com/893487340562-message-attachment
            fields:
              type: object
              description: Fields are provided by AWS to authenticate and validate the request. All fields should be included in form-data when performing upload request.
              example: {}
    AttachmentResponse:
      type: object
      properties:
        total:
          description: Total attachments
          type: number
          example: 10
        attachments:
          description: List attachments
          type: array
          items:
            type: object
            properties:
              filename:
                description: File name
                type: string
                example: order.docx
              bucket:
                description: Bucket name
                type: string
                example: epilot-playground-upload-document
              object_key:
                description: Object key
                type: string
                example: 9f561bea-f0d9-4e96-b7a9-879fc1643ac0.docx
              url:
                description: URL
                type: string
                example: https://epilot-playground-upload-document.s3.eu-central-1.amazonaws.com/9f561bea-f0d9-4e96-b7a9-879fc1643ac0.docx
              document_type:
                description: |
                  Document type:
                  * 0: Static docs
                  * 1: Templates
                type: number
                example: 0
    UserResponse:
      type: object
      properties:
        id:
          type: string
        organization_id:
          type: string
        display_name:
          type: string
          description: 'User''s display name (default: email address)'
          example: Example User
        email:
          type: string
          format: email
        phone:
          type: string
          nullable: true
          example: 1234567890
        preferred_language:
          type: string
          example: de
        image_uri:
          type: object
          additionalProperties: true
          properties:
            original:
              type: string
              format: uri
            thumbnail_32:
              type: string
              format: uri
          example:
            original: https://account-profile-images.epilot.cloud/1/avatar.png
            thumbnail_32: https://account-profile-images.epilot.cloud/1/avatar_32x32.png
        properties:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: profileImageName
              value:
                type: string
                example: avatar.png
            required:
            - name
            - value
    VariableParameters:
      type: object
      properties:
        template_type:
          $ref: '#/components/schemas/TemplateType'
        language:
          type: string
          enum:
          - en
          - de
        main_entity_id:
          type: string
          description: The main entity ID. Use main entity in order to use the variable without schema slug prefix - or just pass directly to other object ID.
          example: 63753437-c9e2-4e83-82bb-b1c666514561
        user_id:
          type: string
          description: User ID
          example: '123452'
        custom_variables:
          $ref: '#/components/schemas/CustomVariables'
      required:
      - template_type
    TemplateType:
      type: string
      enum:
      - email
      - document
    EmailTemplateResponse:
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/EmailTemplateEntity'
        relations:
          type: array
          items:
            type: object
    AsyncEmailTemplateResponse:
      type: object
      required:
      - job_id
      - status
      properties:
        job_id:
          type: string
          description: Job ID of the email template that is requested to replace and generate docs
          example: 8c086140-f33e-4bb7-a993-50c0f2402c7b
        status:
          type: string
          enum:
          - STARTED
          - PROCESSING
          - SUCCESS
          - FAILED
        message:
          type: string
          description: Error message
        doc_progress_count:
          type: object
          description: Progress count of the documents that are needed to generate
          required:
          - total
          - completed
          properties:
            total:
              type: number
              description: Total count
              example: 10
            completed:
              type: number
              description: Completed count
              example: 5
        result:
          type: object
          description: Result of the email template that is replaced along with generated docs
          properties:
            entity:
              $ref: '#/components/schemas/EmailTemplateEntity'
            relations:
              type: array
              items:
                type: object
    SkipCreatingEntities:
      type: boolean
      description: When true, it lets to send only the email by skip creating the thread & message entities.
    CompleteThread:
      type: boolean
      description: Whether the thread is marked as Done immediately after sending the message
      default: false
    BulkSendMessageRequest:
      type: object
      description: |
        It takes a list of entity ids, treating each as a separate mainEntity to construct individual messages.
        For e.g; if there some opportunityIds are provided, then each opportunityId is treated as a separate mainEntity to construct individual messages.
      required:
      - email_template_id
      - recipient_ids
      properties:
        skip_creating_entities:
          $ref: '#/components/schemas/SkipCreatingEntities'
        complete_thread:
          $ref: '#/components/schemas/CompleteThread'
        email_template_id:
          type: string
          description: ID of email template to use for sending bulk emails
          example: 511ceb90-f738-47aa-8b1e-915ace0ae13c
        must_include_unsubscribe_link:
          type: boolean
          description: |
            If true then include unsubscribe link in the email body
          default: false
        recipient_ids:
          type: array
          description: List of entity ids to use as recipients
          items:
            type: string
          example:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
          - 3fa85f64-5717-4562-b3fc-2c963f66afa7
          - 3fa85f64-5717-4562-b3fc-2c963f66afa8
        custom_variables:
          $ref: '#/components/schemas/CustomVariables'
    BulkSendMessageRequestWithQuery:
      type: object
      description: |
        It takes an entity query to derive recipient_ids, treating each as a separate mainEntity to construct individual messages.
        For e.g; if the query is provided as `_schema:opportunity AND status:PENDING`,
          then all the opportunity Ids with status PENDING are treated as separate mainEntity to construct individual messages.
      required:
      - email_template_id
      - recipient_query
      properties:
        skip_creating_entities:
          $ref: '#/components/schemas/SkipCreatingEntities'
        complete_thread:
          $ref: '#/components/schemas/CompleteThread'
        email_template_id:
          type: string
          description: ID of email template to use for sending bulk emails
          example: 511ceb90-f738-47aa-8b1e-915ace0ae13c
        must_include_unsubscribe_link:
          type: boolean
          description: |
            If true then include unsubscribe link in the email body
          default: false
        recipient_query:
          type: string
          description: Entity search query to select recipients
          example: _schema:contact AND consent_email_marketing:active
        custom_variables:
          $ref: '#/components/schemas/CustomVariables'
    CustomVariables:
      description: Custom variables to be replaced in the email template
      type: array
      items:
        type: object
        properties:
          variable:
            type: string
            description: Template Variable Name
            example: '{{abc.xyz}}'
          value:
            type: string
            description: Value to be Replaced
            example: ReplacedValue
    BulkSendMessageJob:
      type: object
      required:
      - job_id
      - status
      - request
      properties:
        org_id:
          $ref: '#/components/schemas/OrgId'
        job_id:
          type: string
          description: Job ID for tracking the status of bulk message action
          example: 8c086140-f33e-4bb7-a993-50c0f2402c7b
        skip_creating_entities:
          $ref: '#/components/schemas/SkipCreatingEntities'
        complete_thread:
          $ref: '#/components/schemas/CompleteThread'
        status:
          type: string
          description: |
            Status of the bulk message action
            * PROCESSING: Bulk message action is processing the request
            * QUEUEING: Bulk message action is generating emails to send in a queue
            * SENDING: Bulk message action is sending emails from the queue
            * SUCCESS: Bulk message action is completed successfully
            * FAILED: Bulk message action is failed
            * CANCELLED: Bulk message action was cancelled
          enum:
          - PROCESSING
          - QUEUEING
          - APPROVAL
          - SENDING
          - SUCCESS
          - FAILED
          - CANCELLED
        request:
          oneOf:
          - $ref: '#/components/schemas/BulkSendMessageRequest'
          - $ref: '#/components/schemas/BulkSendMessageRequestWithQuery'
        created_by:
          $ref: '#/components/schemas/CreatedBy'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
        approved_at:
          $ref: '#/components/schemas/ApprovedAt'
        approve_action:
          $ref: '#/components/schemas/ApproveAction'
        task_token:
          $ref: '#/components/schemas/TaskToken'
        total_queued:
          type: integer
          description: Total number of emails generated and queued for sending
          example: 100
          deprecated: true
        queued:
          type: array
          description: List of entity ids that are queued for sending
          items:
            type: object
            required:
            - entity_id
            - email_to
            - email_with_consent
            properties:
              entity_id:
                type: string
                description: Recipient Entity ID
                example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
              email_to:
                description: Recipient emails
                type: array
                items:
                  type: string
                  description: Recipient email address
                  example: recipient@example.com
              email_with_consent:
                description: Recipient emails with consent
                type: array
                items:
                  type: string
                  description: Recipient email address
                  example: recipient@example.com
        sent:
          type: array
          description: List of entity ids and message ids that were sent successfully
          items:
            type: object
            required:
            - entity_id
            - message_id
            properties:
              entity_id:
                type: string
                description: Recipient Entity ID
                example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
              message_id:
                type: string
                description: Message ID
                example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
              email_to:
                type: array
                items:
                  type: string
                  description: Recipient email address
                  example: recipient@example.com
        failed:
          type: array
          description: List of entity ids that were skipped or failed
          items:
            type: object
            required:
            - entity_id
            - error
            properties:
              entity_id:
                type: string
                description: Recipient Entity ID
                example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
              error:
                type: string
                description: Error message
              email_to:
                type: array
                items:
                  type: string
                  description: Recipient email address
                  example: recipient@example.com
    CreateSystemTemplatesReq:
      type: object
      properties:
        template_names:
          type: array
          items:
            type: string
          example:
          - DoubleOptIn_Email_DE
          - Einladung Kundenportal
          - Partner_Kooperation_Email_DE
      required:
      - template_names
    CreateSystemTemplatesResp:
      type: array
      items:
        $ref: '#/components/schemas/BaseEntity'
    OrgId:
      type: string
      description: Organization ID
      example: '206801'
      readOnly: true
    CreatedBy:
      type: string
      description: User ID who created the bulk message action
      example: '1234'
      readOnly: true
    CreatedAt:
      type: string
      description: Time when the bulk message action was created
      format: date-time
      readOnly: true
    UpdatedAt:
      type: string
      description: Time when the bulk message action was last updated
      format: date-time
      readOnly: true
    ApprovedAt:
      type: string
      description: Time when the bulk message action was last approved
      format: date-time
      readOnly: true
    ApproveAction:
      type: string
      description: |
        Type of approval action for the bulk message request.
        * APPROVE_WITH_CONSENT: Approve the bulk message request and send emails to queued recipients with consent
        * APPROVE_ALL: Approve the bulk message request and send emails to all queued recipients, including those without consent
      enum:
      - APPROVE_WITH_CONSENT
      - APPROVE_ALL
      readOnly: true
    TaskToken:
      type: string
      description: Task token to approve or cancel the bulk message action
      example: 8c086140-f33e-4bb7-a993-50c0f2402c7b
      readOnly: true
servers:
- url: https://email-template.sls.epilot.io

