openapi: 3.0.3
info:
  title: DeBounce Email Validation Account Bulk API
  description: 'DeBounce is an email validation and verification REST API that helps developers ensure the deliverability and quality of email addresses at scale. The API supports real-time single email validation, asynchronous bulk list processing, and data enrichment via reverse email lookup. It detects disposable addresses, role-based emails, catch-all domains, syntax errors, and performs MX record and SMTP-level mailbox verification.

    '
  version: 1.0.0
  contact:
    name: DeBounce Support
    url: https://debounce.com/
  license:
    name: MIT
  termsOfService: https://debounce.com/terms/
servers:
- url: https://api.debounce.io
  description: DeBounce production API
security:
- ApiKeyQuery: []
tags:
- name: Bulk
  description: Bulk email list upload and status
paths:
  /v1/bulk/:
    post:
      tags:
      - Bulk
      summary: Upload Email List for Bulk Validation
      description: 'Uploads a list of email addresses for asynchronous bulk validation processing. Bulk validation operates asynchronously and a list ID is returned for polling status or receiving webhook notifications on completion.

        '
      operationId: bulkUpload
      parameters:
      - name: api
        in: query
        required: true
        schema:
          type: string
        description: Your DeBounce API key
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV or TXT file containing email addresses (one per line)
                name:
                  type: string
                  description: Optional name for the bulk list
          application/json:
            schema:
              type: object
              required:
              - emails
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
                  description: Array of email addresses to validate
                name:
                  type: string
                  description: Optional name for the bulk list
      responses:
        '200':
          description: Bulk list upload accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUploadResponse'
              example:
                success: '1'
                list_id: '12345'
                message: File uploaded successfully. Processing started.
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/bulk/{list_id}:
    get:
      tags:
      - Bulk
      summary: Get Bulk Validation Status
      description: 'Retrieves the processing status and results of a previously submitted bulk email validation list. Poll this endpoint to check progress, or use webhooks for completion notifications.

        '
      operationId: getBulkStatus
      parameters:
      - name: api
        in: query
        required: true
        schema:
          type: string
        description: Your DeBounce API key
      - name: list_id
        in: path
        required: true
        schema:
          type: string
        description: The list ID returned from the bulk upload endpoint
      responses:
        '200':
          description: Bulk list status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkStatusResponse'
              example:
                success: '1'
                list_id: '12345'
                status: completed
                total: 1000
                processed: 1000
                safe: 750
                invalid: 150
                risky: 75
                unknown: 25
                download_url: https://api.debounce.io/v1/bulk/12345/download
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: List not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        debounce:
          type: object
          properties:
            error:
              type: string
              description: Human-readable error message
            code:
              type: string
              description: Error code
        success:
          type: string
          enum:
          - '0'
          description: Always '0' for error responses
    BulkUploadResponse:
      type: object
      properties:
        success:
          type: string
          enum:
          - '0'
          - '1'
        list_id:
          type: string
          description: Unique identifier for the submitted bulk list
        message:
          type: string
          description: Status message
    BulkStatusResponse:
      type: object
      properties:
        success:
          type: string
          enum:
          - '0'
          - '1'
        list_id:
          type: string
          description: The bulk list identifier
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          description: Current processing status of the bulk list
        total:
          type: integer
          description: Total number of email addresses in the list
        processed:
          type: integer
          description: Number of email addresses processed so far
        safe:
          type: integer
          description: Count of Safe to Send results
        invalid:
          type: integer
          description: Count of Invalid results
        risky:
          type: integer
          description: Count of Risky results
        unknown:
          type: integer
          description: Count of Unknown results
        download_url:
          type: string
          format: uri
          description: URL to download the completed validation results file
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api
      description: 'DeBounce API key passed as the ''api'' query parameter. Obtain your API key from the DeBounce account dashboard at https://app.debounce.io/.

        '