openapi: 3.0.3
info:
  title: Transactional Email API
  version: 1.0.0
  description: ''
servers:
  - url: https://mail-de.retarus.com/rest/v2
    description: ''
security:
  - httpBasicAuth: []
tags:
  - name: mail
    description: ''
paths:
  /jobs:
    post:
      tags:
        - mail
      description: ''
      operationId: sendJobRequest
      requestBody:
        description: JobRequest - Full Example
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailJobRequest'
            examples:
              minimal:
                $ref: '#/components/examples/EmailJobMinimalRequest'
              example:
                $ref: '#/components/examples/EmailJobExampleRequest'
              complete:
                $ref: '#/components/examples/EmailJobCompleteRequest'
      responses:
        '200':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseAccepted'
              examples:
                accepted:
                  $ref: '#/components/examples/ResponseAccepted'
                partial:
                  $ref: '#/components/examples/ResponseAcceptedPart'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseRejected'
              example:
                meta:
                  jobId: 7fd6ec7a-194e-43d4-b54f-19312bb4124d
                  state:
                    type: REJECTED
                    subType: INVALID_VALUE
                    phase: PRE_PROCESS
                    description: Invalid value for mail.from
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseRejected'
              example:
                meta:
                  jobId: 8764f6fd-7227-40f8-b242-ff21d02845e9
                  state:
                    type: REJECTED
                    subType: FORBIDDEN_SENDER
                    phase: PRE_PROCESS
                    description: >-
                      Unsupported value for mail.from domain - senderDomain not
                      in configured/allowed domains
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseRejected'
              example:
                meta:
                  jobId: 7fd6ec7a-194e-43d4-b54f-19312bb4124d
                  state:
                    type: REJECTED
                    subType: LIMIT_EXCEEDED
                    phase: PRE_PROCESS
                    description: Request rate limit per hour exceeded.
components:
  securitySchemes:
    httpBasicAuth:
      type: http
      scheme: basic
      description: |
        Basic authorization
  schemas:
    EmailJobRequest:
      type: object
      required:
        - mail
        - recipients
        - subject
      properties:
        mail:
          $ref: '#/components/schemas/Mail'
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          minItems: 1
          maxItems: 100
        subject:
          $ref: '#/components/schemas/Subject'
        body:
          $ref: '#/components/schemas/Body'
        alternative:
          $ref: '#/components/schemas/Alternative'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          minItems: 1
          maxItems: 20
        job:
          $ref: '#/components/schemas/Job'
        notification:
          $ref: '#/components/schemas/Notification'
    Subject:
      type: object
      properties:
        content:
          type: string
          maxLength: 500
          description: Email subject. Max length 500 characters.
        template:
          type: string
          description: Template for email subject.
          example: Subject-Standard-Text ${name}
        contentEncoding:
          type: string
          enum:
            - plain
            - base64
            - quoted-printable
          description: default=plain
          example: plain
        contentTransferEncoding:
          type: string
          enum:
            - base64
          example: base64
        charset:
          type: string
          description: default=UTF-8
          example: UTF-8
    Mail:
      type: object
      required:
        - from
      properties:
        from:
          $ref: '#/components/schemas/EmailAddress'
        mimeFrom:
          $ref: '#/components/schemas/EmailAddress'
        replyTo:
          $ref: '#/components/schemas/EmailAddress'
        inReplyTo:
          type: string
          example: <1234@example.com>
        priority:
          $ref: '#/components/schemas/MailPriority'
        xHeaders:
          $ref: '#/components/schemas/EmailHeaders'
    EmailAddress:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          maxLength: 254
          example: john.doe@example.com
    EmailHeaders:
      type: object
      additionalProperties:
        type: string
      description: Header names must start with X- max header count=10
      maxProperties: 10
      example:
        X-MY-ADDITIONAL-HEADER: value1234
    Recipient:
      type: object
      required:
        - mail
      properties:
        mail:
          $ref: '#/components/schemas/RecipientsMail'
        reference:
          type: string
          maxLength: 50
          example: rcpt-632cdc56-6480-406b-8faf-5a7e70876d0c
        features:
          $ref: '#/components/schemas/RecipientFeatures'
    RecipientsMail:
      type: object
      required:
        - to
      properties:
        to:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
          minItems: 1
        cc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
          minItems: 1
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
          minItems: 1
        replyTo:
          $ref: '#/components/schemas/EmailAddress'
        inReplyTo:
          type: string
          example: <1234@example.com>
        priority:
          $ref: '#/components/schemas/MailPriority'
        listUnsubscribe:
          type: string
        listHelp:
          type: string
        xHeaders:
          $ref: '#/components/schemas/EmailHeaders'
    MailPriority:
      type: string
      enum:
        - HIGH
        - NORMAL
        - LOW
      description: default=NORMAL
      example: NORMAL
    RecipientFeatures:
      type: object
      properties:
        openTracking:
          type: object
          properties:
            active:
              type: boolean
        linkTracking:
          type: object
          properties:
            active:
              type: boolean
        templating:
          properties:
            personalization:
              type: object
              additionalProperties:
                type: string
              description: key-value-map with personalization information
              example:
                name: John
                surname: Doe
    Job:
      type: object
      properties:
        referenceJob:
          type: string
          maxLength: 50
          example: 632cdc56-6480-406b-8faf-5a7e70876d0c
        costCenter:
          type: string
          maxLength: 50
          example: cost-center
        campaignId:
          type: string
          maxLength: 50
          example: zOsVEmBBV3TYzTPe
        features:
          $ref: '#/components/schemas/JobFeatures'
    JobFeatures:
      type: object
      properties:
        openTracking:
          type: object
          properties:
            active:
              type: boolean
        linkTracking:
          type: object
          properties:
            active:
              type: boolean
        antivirus:
          type: object
          properties:
            active:
              type: boolean
        templating:
          type: object
          properties:
            active:
              type: boolean
        messageSigning:
          type: object
          properties:
            active:
              type: boolean
        secureDocument:
          type: object
          properties:
            active:
              type: boolean
            filename:
              type: string
              maxLength: 50
            subjectPrefix:
              type: string
              maxLength: 50
            password:
              type: object
              properties:
                password:
                  type: string
                  enum:
                    - MEDIUM
                    - HIGH
                    - VERY_HIGH
    Body:
      type: object
      required:
        - contentType
      properties:
        contentType:
          type: string
          enum:
            - text/plain
            - text/html
          example: text/html
        charset:
          type: string
          description: default=UTF-8
          example: UTF-8
        contentEncoding:
          type: string
          enum:
            - plain
            - quoted-printable
            - base64
          description: default=plain
          example: quoted-printable
        contentTransferEncoding:
          type: string
          enum:
            - base64
          example: base64
        content:
          type: string
          example: <html><body>hello world</body></html>
        template:
          type: string
          description: Template for email body.
    Alternative:
      type: object
      properties:
        charset:
          type: string
          description: default=UTF-8
          example: UTF-8
        contentEncoding:
          type: string
          enum:
            - plain
            - quoted-printable
            - base64
          description: default=plain
          example: quoted-printable
        contentTransferEncoding:
          type: string
          enum:
            - base64
          example: base64
        content:
          type: string
          example: hello world.
        template:
          type: string
          description: Template for email alternative.
    Attachment:
      type: object
      required:
        - name
        - contentType
        - content
      properties:
        name:
          type: string
          example: name.pdf
        contentType:
          type: string
          example: application/pdf
        contentId:
          type: string
          maxLength: 100
        content:
          type: string
          format: byte
          description: base64 encoded content
          example: UmV0YXJ1cyEhCg==
        secureDocument:
          type: boolean
    Notification:
      type: object
      properties:
        endPoint:
          $ref: '#/components/schemas/NotificationEndpoint'
    NotificationEndpoint:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          maxLength: 1000
          example: https://notification-endpoint.example.com/
        headers:
          type: object
          additionalProperties:
            type: string
          description: additional HTTP Headers for the notifications
          example:
            X-REQUEST-ID: 3a5d3643-cc2b-41ba-b54f-9bb6a9de6b18
        authentication:
          $ref: '#/components/schemas/NotificationAuthentication'
    NotificationAuthentication:
      type: object
      required:
        - method
        - user
        - password
      properties:
        method:
          type: string
          enum:
            - BASIC
          example: BASIC
        user:
          type: string
          maxLength: 100
          example: notification-user
        password:
          type: string
          maxLength: 100
          example: dfghoxjuvnzeso374i
    ResponseAccepted:
      type: object
      required:
        - meta
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        content:
          $ref: '#/components/schemas/ResponseContent'
    ResponseRejected:
      type: object
      required:
        - meta
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMetaBasic'
    ResponseMetaBasic:
      type: object
      required:
        - jobId
        - state
      properties:
        jobId:
          type: string
        state:
          $ref: '#/components/schemas/ResponseState'
        accountId:
          type: string
    ResponseMeta:
      type: object
      allOf:
        - $ref: '#/components/schemas/ResponseMetaBasic'
      properties:
        receivedTs:
          type: string
          format: date-time
        campaignId:
          type: string
        costCenter:
          type: string
        referenceJob:
          type: string
    ResponseState:
      type: object
      properties:
        type:
          type: string
        subType:
          type: string
        phase:
          type: string
        description:
          type: string
    ResponseContent:
      type: object
      properties:
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/RecipientResponse'
    RecipientResponse:
      type: object
      required:
        - mail
      properties:
        mail:
          $ref: '#/components/schemas/RecipientMailResponse'
        referenceRecipients:
          type: string
    RecipientMailResponse:
      type: object
      required:
        - to
      properties:
        to:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddressResponse'
        cc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddressResponse'
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddressResponse'
    EmailAddressResponse:
      type: object
      required:
        - id
      allOf:
        - $ref: '#/components/schemas/EmailAddress'
      properties:
        id:
          type: string
          example: 22579950-b1cb-4ad8-be2b-715d63a06fcd#999dc92b#a0b50b76
        validationResult:
          $ref: '#/components/schemas/ValidationResult'
    ValidationResult:
      type: object
      properties:
        classifier:
          type: string
        message:
          type: string
  examples:
    EmailJobMinimalRequest:
      summary: minimal
      value:
        subject:
          content: minimal subject
        recipients:
          - mail:
              to:
                - email: test-01@null.dev.retloc
        mail:
          from:
            email: test@bot.com
    EmailJobExampleRequest:
      summary: example
      value:
        mail:
          from:
            email: john.doe@example.com
        recipients:
          - mail:
              to:
                - email: jane.doe@example.com
        subject:
          content: Hello
        body:
          contentType: text/html
          content: <html><body>hello world</body></html>
        alternative:
          content: hello world
        attachments:
          - name: name.pdf
            contentType: application/pdf
            content: aGVsbG8gd29ybGQ=
        job:
          referenceJob: 632cdc56-6480-406b-8faf-5a7e70876d0c
          costCenter: cost-center
          campaignId: zOsVEmBBV3TYzTPe
    EmailJobCompleteRequest:
      summary: complete
      value:
        mail:
          from:
            email: john.doe@example.com
          mimeFrom:
            email: john.doe@example.com
          replyTo:
            email: john.doe@example.com
          inReplyTo: <1234@example.com>
          priority: NORMAL
          xHeaders:
            X-MY-ADDITIONAL-HEADER: value1234
        recipients:
          - mail:
              to:
                - email: john.doe@example.com
              cc:
                - email: john.doe@example.com
              bcc:
                - email: john.doe@example.com
              replyTo:
                email: john.doe@example.com
              inReplyTo: <1234@example.com>
              priority: NORMAL
              listUnsubscribe: string
              listHelp: string
              xHeaders:
                X-MY-ADDITIONAL-HEADER: value1234
            reference: rcpt-632cdc56-6480-406b-8faf-5a7e70876d0c
            features:
              openTracking:
                active: true
              linkTracking:
                active: true
              templating:
                personalization:
                  name: John
                  surname: Doe
        subject:
          content: string
          template: Subject-Standard-Text ${name}
          contentEncoding: plain
          contentTransferEncoding: base64
          charset: UTF-8
        body:
          contentType: text/html
          charset: UTF-8
          contentEncoding: quoted-printable
          contentTransferEncoding: base64
          content: <html><body>hello world</body></html>
          template: string
        alternative:
          charset: UTF-8
          contentEncoding: quoted-printable
          contentTransferEncoding: base64
          content: hello world.
          template: string
        attachments:
          - name: name.pdf
            contentType: application/pdf
            contentId: string
            content: string
            secureDocument: true
        job:
          referenceJob: 632cdc56-6480-406b-8faf-5a7e70876d0c
          costCenter: cost-center
          campaignId: zOsVEmBBV3TYzTPe
          features:
            openTracking:
              active: true
            linkTracking:
              active: true
            antivirus:
              active: true
            templating:
              active: true
            messageSigning:
              active: true
            secureDocument:
              active: true
              filename: string
              subjectPrefix: string
              password:
                password: MEDIUM
        notification:
          endPoint:
            url: https://notification-endpoint.example.com/
            headers:
              X-REQUEST-ID: 3a5d3643-cc2b-41ba-b54f-9bb6a9de6b18
            authentication:
              method: BASIC
              user: notification-user
              password: dfghoxjuvnzeso374i
    ResponseAccepted:
      summary: accepted
      value:
        meta:
          jobId: 22579950-b1cb-4ad8-be2b-715d63a06fcd
          state:
            type: ACCEPTED
            subType: FULL
            phase: PRE_PROCESS
        content:
          recipients:
            - mail:
                to:
                  - email: john.doe@example.com
                    id: 22579950-b1cb-4ad8-be2b-715d63a06fcd#999dc92b#a0b50b76
    ResponseAcceptedPart:
      summary: partial accepted
      value:
        meta:
          jobId: 22579950-b1cb-4ad8-be2b-715d63a06fcd
          receivedTs: '2023-02-02T08:51:42.097Z'
          state:
            type: ACCEPTED
            subType: PART
            phase: PRE_PROCESS
        content:
          recipients:
            - mail:
                to:
                  - id: 22579950-b1cb-4ad8-be2b-715d63a06fcd#999dc92b#92059835
                    email: jane.doe@example.com
                  - id: 22579950-b1cb-4ad8-be2b-715d63a06fcd#999dc92b#a0b50b76
                    email: not-an-address
                    validationResult:
                      classifier: INVALID_FORMAT
