EmailConnect by XADI API v1 - Emails API

openapi: 3.2.0
info:
  title: EmailConnect.eu API v1 - Emails API
  version: 1.0.0
  description: '# EmailConnect.eu API Documentation


    Welcome to the EmailConnect.eu API!'
  contact:
    name: EmailConnect.eu Support
    email: support@emailconnect.eu
    url: https://app.emailconnect.eu
  license:
    name: Terms of Service
    url: https://emailconnect.eu/terms-of-service
servers:
- url: https://app.emailconnect.eu
  description: Production server
tags:
- name: API v1 - Emails
  description: Look up one email and its stored attachments with their fetch counts, or delete it after processing. Looking up requires the `logs:read` API key scope, which includes stored message content. Deleting an email record and its attachments requires a Business+ plan and the `emails:delete` API key scope.
paths:
  /api/v1/emails/{messageId}:
    get:
      tags:
      - API v1 - Emails
      summary: Get one email
      description: 'Returns the log entry for one email: delivery status, attempt count, the last error and the stored webhook payload. The same object as an item of `GET /api/v1/logs`, plus `attachments`: the files stored for the email, with how often each download link was fetched. Requires `logs:read` API key scope. An email that does not exist, belongs to another account or is past its retention returns 404. A verification ping carries a `webhook-id` with no stored email and also returns 404.'
      security:
      - userApiKey: []
      parameters:
      - name: messageId
        in: path
        required: true
        schema:
          type: string
          example: msg_cmbw6hopl002uru1qqyx7b18a
        description: 'Identifies the email. Either `msg_<id>`, the value of the `webhook-id` header on the delivery (preferred: no encoding needed), or the RFC 5322 Message-ID with or without angle brackets, percent-encoded. If one message was delivered to several of your addresses, its Message-ID matches several emails and the call answers 409; use the `msg_…` id from the `webhook-id` header instead.'
      responses:
        '200':
          description: The email log entry
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/EmailLog'
                - type: object
                  properties:
                    attachments:
                      type: array
                      description: Stored files of this email with fetch statistics
                      items:
                        $ref: '#/components/schemas/AttachmentInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden — API key lacks `logs:read` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Email not found, not owned by the caller, or already deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The Message-ID matches more than one email of this account. Repeat the call with one of the listed ids.
          content:
            application/json:
              schema:
                type: object
                required:
                - statusCode
                - error
                - message
                - matches
                properties:
                  statusCode:
                    type: integer
                    example: 409
                  error:
                    type: string
                    example: Conflict
                  message:
                    type: string
                  matches:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: string
                          description: The email id, `msg_…`, as sent in the `webhook-id` header
                        recipient:
                          type:
                          - string
                          - 'null'
                          description: The address this copy was delivered to
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiV1EmailsByMessageId
      x-operation-id-source: derived
    delete:
      tags:
      - API v1 - Emails
      summary: Delete email and attachments
      description: Permanently delete an email record and all associated attachments (both database records and S3 objects). The email must be owned by the authenticated user. Requires Business+ plan and an API key with the `emails:delete` scope.
      security:
      - userApiKey: []
      parameters:
      - name: messageId
        in: path
        required: true
        schema:
          type: string
          example: <unique-id@mail.example.com>
        description: 'Identifies the email. Either `msg_<id>`, the value of the `webhook-id` header on the delivery (preferred: no encoding needed), or the RFC 5322 Message-ID with or without angle brackets, percent-encoded. If one message was delivered to several of your addresses, its Message-ID matches several emails and the call answers 409; use the `msg_…` id from the `webhook-id` header instead.'
      responses:
        '200':
          description: Email deleted successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - messageId
                - attachmentsDeleted
                properties:
                  success:
                    type: boolean
                    example: true
                  messageId:
                    type: string
                    example: <unique-id@mail.example.com>
                  attachmentsDeleted:
                    type: integer
                    description: Number of S3 attachment objects cleaned up
                    example: 2
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Payment Required — Business+ plan needed
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 402
                  error:
                    type: string
                    example: Payment Required
                  message:
                    type: string
        '403':
          description: Forbidden — API key lacks `emails:delete` scope
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 403
                  error:
                    type: string
                    example: Forbidden
                  message:
                    type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The Message-ID matches more than one email of this account. Repeat the call with one of the listed ids.
          content:
            application/json:
              schema:
                type: object
                required:
                - statusCode
                - error
                - message
                - matches
                properties:
                  statusCode:
                    type: integer
                    example: 409
                  error:
                    type: string
                    example: Conflict
                  message:
                    type: string
                  matches:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: string
                          description: The email id, `msg_…`, as sent in the `webhook-id` header
                        recipient:
                          type:
                          - string
                          - 'null'
                          description: The address this copy was delivered to
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: deleteApiV1EmailsByMessageId
      x-operation-id-source: derived
  /api/v1/emails/{messageId}/attachments:
    get:
      tags:
      - API v1 - Emails
      summary: List stored attachments of an email
      description: 'Returns the files stored for an email, with their status and how often each download link was fetched. Only offloaded files are listed: attachments delivered inline in the payload have no entry. Statistics are deleted with the email. Requires an API key with the `logs:read` scope.'
      security:
      - userApiKey: []
      parameters:
      - name: messageId
        in: path
        required: true
        schema:
          type: string
          example: msg_cmbw6hopl002uru1qqyx7b18a
        description: 'Identifies the email. Either `msg_<id>`, the value of the `webhook-id` header on the delivery (preferred: no encoding needed), or the RFC 5322 Message-ID with or without angle brackets, percent-encoded. If one message was delivered to several of your addresses, its Message-ID matches several emails and the call answers 409; use the `msg_…` id from the `webhook-id` header instead.'
      responses:
        '200':
          description: Stored attachments of the email, oldest first
          content:
            application/json:
              schema:
                type: object
                required:
                - attachments
                properties:
                  attachments:
                    type: array
                    items:
                      $ref: '#/components/schemas/AttachmentInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden — API key lacks `logs:read` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Email not found, not yours, or past its retention
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The Message-ID matches more than one email of this account. Repeat the call with one of the listed ids.
          content:
            application/json:
              schema:
                type: object
                required:
                - statusCode
                - error
                - message
                - matches
                properties:
                  statusCode:
                    type: integer
                    example: 409
                  error:
                    type: string
                    example: Conflict
                  message:
                    type: string
                  matches:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: string
                          description: The email id, `msg_…`, as sent in the `webhook-id` header
                        recipient:
                          type:
                          - string
                          - 'null'
                          description: The address this copy was delivered to
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiV1EmailsByMessageIdAttachments
      x-operation-id-source: derived
  /api/v1/attachments/{fileId}:
    get:
      tags:
      - API v1 - Emails
      summary: Get a stored attachment and its fetch statistics
      description: Returns status, storage location and how often the download link was fetched, for one file. `downloadCount` counts times the download link was fetched (redirects issued), not completed transfers. Requires an API key with the `logs:read` scope.
      security:
      - userApiKey: []
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
          example: cmbw6hopl002uru1qqyx7b18a
        description: The file ID, the path segment of the payload `downloadUrl`
      responses:
        '200':
          description: The stored attachment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden — API key lacks `logs:read` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: File not found or not yours
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiV1AttachmentsByFileId
      x-operation-id-source: derived
components:
  schemas:
    EmailLog:
      type: object
      properties:
        id:
          type: string
          example: cmbw6hopl002uru1qqyx7b18a
        messageId:
          type: string
          example: <20261009114502.7f3a@mail.example.com>
          description: The RFC 5322 Message-ID chosen by the sender, as stored.
        fromAddress:
          type: string
          example: sender@example.com
        toAddresses:
          type: array
          items:
            type: string
          example:
          - recipient@mydomain.com
        subject:
          type:
          - string
          - 'null'
          example: Test Email Subject
        deliveryStatus:
          type: string
          enum:
          - PENDING
          - DELIVERED
          - FAILED
          - RETRYING
          - EXPIRED
          - REJECTED
          example: DELIVERED
        deliveryAttempts:
          type: integer
          example: 1
        lastAttemptAt:
          type:
          - string
          - 'null'
          format: date-time
        deliveredAt:
          type:
          - string
          - 'null'
          format: date-time
        errorMessage:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        isTestWebhook:
          type: boolean
          example: false
        webhookPayload:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: The payload as stored at ingest, in the shape of that time. Null when none was stored. For rejected mail it is the parsed message with internal `_rejection*` fields, before the alias filters and the payload template were applied. A replay re-sends it as stored. Data-residency messages hold a marker payload without the body.
        httpStatus:
          type:
          - integer
          - 'null'
          example: 200
          description: HTTP response status from webhook delivery
        domain:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
            domain:
              type: string
        alias:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
            email:
              type: string
            webhook:
              type:
              - object
              - 'null'
              properties:
                id:
                  type: string
                name:
                  type: string
                url:
                  type: string
                  format: uri
        webhook:
          type:
          - object
          - 'null'
          description: Direct webhook relationship for test webhooks
          properties:
            id:
              type: string
            name:
              type: string
            url:
              type: string
              format: uri
      required:
      - id
      - messageId
      - fromAddress
      - toAddresses
      - deliveryStatus
      - deliveryAttempts
      - createdAt
      - expiresAt
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        error:
          type: string
          example: Bad Request
        message:
          type: string
          example: Invalid input
      required:
      - statusCode
      - error
      - message
    AttachmentInfo:
      type: object
      description: 'A file stored for an email. Only offloaded files are listed: attachments delivered inline in the payload, excluded or rejected ones, and a file whose synchronous upload failed have no entry.'
      required:
      - fileId
      - filename
      - contentType
      - size
      - status
      - failureReason
      - storage
      - storageConnectionName
      - downloadUrl
      - createdAt
      - expiresAt
      - downloadCount
      - lastDownloadAt
      properties:
        fileId:
          type: string
          example: cmbw6hopl002uru1qqyx7b18a
        filename:
          type: string
          example: invoice.pdf
        contentType:
          type: string
          example: application/pdf
        size:
          type: integer
          description: Size in bytes
          example: 248113
        status:
          type: string
          enum:
          - pending
          - completed
          - failed
          - expired
          description: '`pending`: still uploading. `completed`: available. `failed`: could not be stored. `expired`: the email reached the end of its retention.'
        failureReason:
          type:
          - string
          - 'null'
          enum:
          - content-unreadable
          - storage-unreachable
          - storage-rejected
          - internal
          description: Why storing failed. Set only when `status` is `failed`.
        storage:
          type: string
          enum:
          - platform
          - custom
          description: Whether the file is in EmailConnect storage or in your own bucket.
        storageConnectionName:
          type:
          - string
          - 'null'
          example: My AWS Bucket
          description: The name of your storage connection the file was stored through. Null for EmailConnect storage, and when the connection no longer exists.
        downloadUrl:
          type: string
          description: The tracked download URL on EmailConnect, as sent in the webhook payload.
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          description: When the email, and with it this file and these statistics, is deleted.
        downloadCount:
          type: integer
          description: Times the download link was fetched. Counts redirects issued, not files received.
          example: 1
        lastDownloadAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When the download link was last fetched.
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed or missing API key for user endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key for user authentication. Find your API key in your account settings.