openapi: 3.0.1
info:
  title: Email Channel Service API Specification
  description: |
    This page describes how to integrate with the **Email Channel Service** on a technical level.

    This service is a specialized downstream service, typically called by the central Notification Service. Its sole
    responsibility is to handle the formatting and dispatching of email notifications.

    -----

    ## REST Resources

    The Email Channel Service provides a single resource for creating and sending an **email notification**.

    ### The Email Notification Resource

    An **email notification** request defines everything needed to send a single email. It consists of:
    * **`reference`**: A unique ID for tracking this specific send request.
    * **`to`**, **`from`**, **`cc`**, **`bcc`**: Lists of recipients, senders, and other parties.
    * **`subject`**: The subject line of the email.
    * **`content`**: A list of content objects, typically `text/plain` and `text/html`, for the email body.
    * **`attachments`**: A list of Base64-encoded file attachments.

    An example of an **email notification request** in JSON format:

    ```json
    {
      "reference": "email_ref_98765_xyz",
      "to": [
        "Peter Smith <peter.smith@example.com>"
      ],
      "from": [
        "Banqup <noreply@banqup.com>"
      ],
      "replyTo": [
        "Support <support@banqup.com>"
      ],
      "subject": "Your new invoice INV-1024",
      "content": [
        {
          "type": "text/plain",
          "value": "Hello Peter, your new invoice INV-1024 is available."
        },
        {
          "type": "text/html",
          "value": "<h1>Hello Peter,</h1><p>Your new invoice <strong>INV-1024</strong> is available.</p>"
        }
      ],
      "attachments": [
        {
          "content": "SGVsbG8gd29ybGQsIHRoaXMgaXMgYSB0ZXN0IFBERg==",
          "id": "doc_cid_123",
          "disposition": "attachment",
          "filename": "invoice-1024.pdf"
        }
      ]
    }
    ```

    When this email is successfully queued for sending, the service returns a unique **notificationId**:

    ```json
    {
      "notificationId": "e0c9b2a8-1b7c-4b3d-811c-9e2b6a4a1f2c"
    }
    ```

    -----

    ## Sending an Email

    To send a new email, you'll perform a **POST** request to the [**/core/email/v1/emails
    **](../../../docs/communication/email/send-email) endpoint, providing the full email
    notification object in the request body.

    ```http
    POST /v1/emails
    Content-Type: application/json

    {
      "reference": "email_ref_98765_xyz",
      "to": [
        "Peter Smith <peter.smith@example.com>"
      ],
      "from": [
        "Banqup <noreply@banqup.com>"
      ],
      "subject": "Your new invoice INV-1024",
      "content": [
        {
          "type": "text/html",
          "value": "<h1>Hello Peter,</h1><p>Your invoice is ready.</p>"
        }
      ]
    }
    ```

    A successful response (HTTP `202 Accepted`) will return the `notificationId` confirming the email has been
    accepted for delivery.

    -----

    ## Security

    Access to send emails is controlled by the **`email_send`** security scope. All requests to the Email Channel API
    must be authenticated using an OAuth security scheme and include a token with the required scope.
  version: 2.0.4
servers:
- description: ''
  url: https://api.cve.btx.eu.banqup.com/core/email
paths: {}
components:
  schemas:
    Attachments:
      required:
      - content
      - disposition
      - filename
      - id
      type: object
      properties:
        content:
          minLength: 1
          type: string
          description: The Base64-encoded content of the file.
          example: SGVsbG8sIHdvcmxkIQ==
        id:
          minLength: 1
          type: string
          description: A unique content ID (cid) for the attachment, used for inline
            images.
          example: my_image_cid
        disposition:
          minLength: 1
          type: string
          description: Content disposition (e.g., 'attachment' for download or 'inline'
            for display).
          example: attachment
        filename:
          minLength: 1
          type: string
          description: The name of the file.
          example: invoice.pdf
      description: Represents a file attachment to be included in the email.
      example:
        content: SGVsbG8sIHdvcmxkIQ==
        id: invoice_pdf_123
        disposition: attachment
        filename: invoice.pdf
    Content:
      required:
      - type
      - value
      type: object
      properties:
        type:
          minLength: 1
          type: string
          description: The MIME type of the content.
          example: text/html
        value:
          minLength: 1
          type: string
          description: The actual content body.
          example: <h1>Hello</h1><p>This is your email.</p>
      description: Represents one part of the email's content (e.g., HTML or plain
        text).
      example:
        type: text/html
        value: <h1>Hello</h1><p>This is your email.</p>
    EmailNotification:
      required:
      - reference
      - subject
      - to
      type: object
      properties:
        reference:
          minLength: 1
          type: string
          description: A unique reference for this notification request.
          example: email_ref_98765_xyz
        to:
          minItems: 1
          type: array
          description: A list of recipient email addresses. (e.g., "Foo Bar <foo@bar.be>")
          items:
            pattern: "^(.*<([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)>)$|^([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)$"
            type: string
            description: A list of recipient email addresses. (e.g., "Foo Bar <foo@bar.be>")
        from:
          type: array
          description: A list of sender email addresses. (e.g., "Company <noreply@company.com>")
          items:
            pattern: "^(.*<([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)>)$|^([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)$"
            type: string
            description: A list of sender email addresses. (e.g., "Company <noreply@company.com>")
        replyTo:
          type: array
          description: A list of reply-to email addresses.
          items:
            pattern: "^(.*<([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)>)$|^([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)$"
            type: string
            description: A list of reply-to email addresses.
        cc:
          type: array
          description: A list of carbon copy (CC) email addresses.
          items:
            pattern: "^(.*<([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)>)$|^([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)$"
            type: string
            description: A list of carbon copy (CC) email addresses.
        bcc:
          type: array
          description: A list of blind carbon copy (BCC) email addresses.
          items:
            pattern: "^(.*<([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)>)$|^([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)$"
            type: string
            description: A list of blind carbon copy (BCC) email addresses.
        subject:
          minLength: 1
          type: string
          description: The subject line of the email.
          example: Your new invoice INV-1024
        content:
          type: array
          description: A list of content objects, e.g., for text/plain and text/html
            versions.
          items:
            $ref: '#/components/schemas/Content'
        attachments:
          type: array
          description: A list of file attachments.
          items:
            $ref: '#/components/schemas/Attachments'
      description: Request body to send an Email notification.
      example:
        reference: email_ref_98765_xyz
        to:
        - Peter Smith <peter.smith@example.com>
        from:
        - Banqup <noreply@banqup.com>
        replyTo:
        - Support <support@banqup.com>
        cc:
        - manager@example.com
        bcc:
        - audit@example.com
        subject: Your new invoice INV-1024
        content:
        - type: text/plain
          value: Hello Peter, your new invoice INV-1024 is available. Regards, The
            Banqup Team.
        - type: text/html
          value: <h1>Hello Peter,</h1><p>Your new invoice <strong>INV-1024</strong>
            is available.</p><p>Regards,<br/>The Banqup Team.</p>
        attachments:
        - content: SGVsbG8gd29ybGQsIHRoaXMgaXMgYSB0ZXN0IFBERg==
          id: doc_cid_123
          disposition: attachment
          filename: invoice-1024.pdf
    EmailNotificationResponse:
      required:
      - notificationId
      type: object
      properties:
        notificationId:
          minLength: 1
          type: string
          description: The unique identifier assigned to the notification.
          format: uuid
          example: e0c9b2a8-1b7c-4b3d-811c-9e2b6a4a1f2c
      description: Response containing the unique identifier of the email notification.
      example:
        notificationId: e0c9b2a8-1b7c-4b3d-811c-9e2b6a4a1f2c
    ApiErrorProblemDetail:
      required:
      - error
      - requestId
      - timestamp
      type: object
      properties:
        status:
          type: integer
          format: int32
        error:
          type: string
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri
        problems:
          type: array
          items:
            $ref: '#/components/schemas/NestedProblem'
        properties:
          type: object
          additionalProperties:
            type: object
    NestedProblem:
      required:
      - detail
      - error
      - title
      type: object
      properties:
        error:
          type: string
        title:
          type: string
        detail:
          type: string
        type:
          type: string
          format: uri
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.cve.btx.eu.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.cve.btx.eu.banqup.com/oauth2/auth
          tokenUrl: https://api.cve.btx.eu.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
