EmailConnect by XADI Webhook Alias API

openapi: 3.2.0
info:
  title: EmailConnect.eu Webhook Alias 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: Webhook-Alias
  description: Atomic operations for creating webhooks and aliases together. Ideal for n8n integrations and simplified setup workflows.
  externalDocs:
    description: Webhook-Alias integration guide
    url: https://emailconnect.eu/help/webhook-alias-atomic-endpoint
paths:
  /api/webhooks/alias:
    post:
      tags:
      - Webhook-Alias
      summary: Create webhook and alias in one atomic operation
      description: 'Creates a webhook and alias together in a single atomic operation.

        Supports both catch-all (*@domain.com) and specific (localpart@domain.com) aliases.

        For catch-all aliases, optionally syncs the webhook with the domain''s webhook.'
      security:
      - userApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookAliasRequest'
            examples:
              catchall:
                summary: Create catch-all alias with webhook
                value:
                  domainId: domain-123
                  webhookUrl: https://myapp.com/webhook
                  webhookName: My Catch-All Webhook
                  webhookDescription: Handles all emails for this domain
                  aliasType: catchall
                  syncWithDomain: true
              specific:
                summary: Create specific alias with webhook
                value:
                  domainId: domain-123
                  webhookUrl: https://myapp.com/webhook/support
                  webhookName: Support Webhook
                  webhookDescription: Handles support emails
                  aliasType: specific
                  localPart: support
                  syncWithDomain: false
      responses:
        '201':
          description: Webhook and alias created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWebhookAliasResponse'
        '400':
          description: Bad request - validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookAliasErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Domain not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookAliasErrorResponse'
        '409':
          description: Conflict - alias already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookAliasErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookAliasErrorResponse'
      operationId: postApiWebhooksAlias
      x-operation-id-source: derived
components:
  schemas:
    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
    CreateWebhookAliasRequest:
      type: object
      required:
      - domainId
      - webhookUrl
      - webhookName
      - aliasType
      properties:
        domainId:
          type: string
          description: ID of the domain to create the alias for
        webhookUrl:
          type: string
          format: uri
          description: URL for the webhook endpoint
        webhookName:
          type: string
          minLength: 1
          maxLength: 100
          description: Name for the webhook
        webhookDescription:
          type: string
          maxLength: 500
          description: Optional description for the webhook
        aliasType:
          type: string
          enum:
          - catchall
          - specific
          description: Type of alias to create - catchall (*@domain.com) or specific (localpart@domain.com)
        localPart:
          type: string
          minLength: 1
          maxLength: 64
          description: Local part for specific aliases (required when aliasType is "specific")
        syncWithDomain:
          type: boolean
          default: true
          description: 'For catch-all aliases, whether to sync webhook with domain webhook (default: true)'
    CreateWebhookAliasResponse:
      type: object
      properties:
        success:
          type: boolean
        webhook:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            url:
              type: string
            verified:
              type: boolean
            verificationToken:
              type:
              - string
              - 'null'
              description: Token for manual verification if auto-verify is false
            createdAt:
              type: string
              format: date-time
        alias:
          type: object
          properties:
            id:
              type: string
            email:
              type: string
            active:
              type: boolean
            createdAt:
              type: string
              format: date-time
        domain:
          type:
          - object
          - 'null'
          description: Domain information if webhook was synced with domain
          properties:
            id:
              type: string
            domain:
              type: string
            webhookUpdated:
              type: boolean
        message:
          type: string
          description: Success message with details about the operation
    WebhookAliasErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
        details:
          type:
          - object
          - 'null'
          properties:
            field:
              type: string
            code:
              type: string
            message:
              type: string
  responses:
    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.