EmailConnect by XADI API v1 - Logs API

openapi: 3.2.0
info:
  title: EmailConnect.eu API v1 - Logs 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 - Logs
  description: Programmatic access to email processing logs with filtering and retry capabilities. Requires `logs:read` or `logs:retry` API key scope. `logs:read` reads delivery logs, including stored message content.
paths:
  /api/v1/logs:
    get:
      tags:
      - API v1 - Logs
      summary: List email processing logs
      description: Retrieve email processing logs with filtering options, newest first. Entries created at the same instant keep a stable order, so paging with `offset` neither repeats nor skips them. Requires `logs:read` API key scope.
      security:
      - userApiKey: []
      parameters:
      - name: domainId
        in: query
        schema:
          type: string
        description: Filter logs by domain ID
      - name: aliasId
        in: query
        schema:
          type: string
        description: Filter logs by alias ID
      - name: status
        in: query
        schema:
          type: string
          enum:
          - PENDING
          - DELIVERED
          - FAILED
          - RETRYING
          - EXPIRED
          - REJECTED
        description: Filter logs by delivery status. `REJECTED` covers mail blocked by an alias rule or spam score, and deliveries the receiver answered with 413. Mail rejected on a system domain (`user.emailconnect.eu`) is not recorded and cannot be listed.
      - name: since
        in: query
        schema:
          type: string
          format: date-time
        description: Only logs created at or after this instant (ISO 8601, inclusive). A `+` in a UTC offset must be percent-encoded as `%2B`.
      - name: until
        in: query
        schema:
          type: string
          format: date-time
        description: 'Only logs created before this instant (ISO 8601, exclusive). Must not be earlier than `since`: a `since` later than `until` is a 400. A `+` in a UTC offset must be percent-encoded as `%2B`.'
      - name: testWebhooksOnly
        in: query
        schema:
          type: boolean
        description: Show only test webhook calls
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 100
        description: Number of logs to return
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
        description: Number of logs to skip for pagination
      responses:
        '200':
          description: A list of email logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailLog'
                  total:
                    type: integer
                  hasMore:
                    type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden — API key lacks `logs:read` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiV1Logs
      x-operation-id-source: derived
  /api/v1/logs/{messageId}/retry:
    post:
      tags:
      - API v1 - Logs
      summary: Retry/replay webhook delivery
      description: Manually retry a failed/expired webhook delivery, or replay a delivered webhook. Available on all plans. Rate limited per message (30s cooldown) and per user (sliding window). While a delivery of the message is still in progress (its first one, or an earlier retry) the call answers 409. Requires `logs:retry` API key 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: Webhook retry queued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Webhook retry queued successfully
                  jobId:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden — API key lacks `logs:retry` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Either the Message-ID matches more than one email of this account (`matches` lists them; repeat the call with one of the listed ids), or a delivery of this email is already in progress (no `matches`; retry once it has finished).
          content:
            application/json:
              schema:
                type: object
                required:
                - statusCode
                - error
                - message
                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
        '429':
          description: Too Many Requests — 30s cooldown between retries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postApiV1LogsByMessageIdRetry
      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
  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'
    BadRequest:
      description: Invalid request payload or parameters.
      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.