openapi: 3.0.3
info:
  title: DeBounce Email Account Validation 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: Validation
  description: Email address validation endpoints
paths:
  /v1/:
    get:
      tags:
      - Validation
      summary: Validate Single Email Address
      description: 'Validates a single email address and returns detailed validation results including deliverability status, disposable detection, role-based detection, free email provider detection, and optional data enrichment. Up to 5 concurrent calls are supported.

        '
      operationId: validateEmail
      parameters:
      - name: api
        in: query
        required: true
        schema:
          type: string
          example: YOUR_API_KEY
        description: Your DeBounce API key
      - name: email
        in: query
        required: true
        schema:
          type: string
          format: email
          example: test@example.com
        description: The email address to validate
      - name: photo
        in: query
        required: false
        schema:
          type: boolean
        description: If true, returns a profile photo URL (additional credits apply)
      - name: append
        in: query
        required: false
        schema:
          type: boolean
        description: If true, enriches response with full name and avatar (additional credits apply)
      - name: gsuite
        in: query
        required: false
        schema:
          type: boolean
        description: If true, detects G Suite accept-all emails
      responses:
        '200':
          description: Validation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleValidationResponse'
              examples:
                safe_to_send:
                  summary: Safe to Send example
                  value:
                    debounce:
                      email: someemail@gmail.com
                      code: '5'
                      role: 'false'
                      free_email: 'true'
                      result: Safe to Send
                      reason: Deliverable
                      send_transactional: '1'
                      did_you_mean: ''
                    success: '1'
                    balance: '329918'
                invalid:
                  summary: Invalid email example
                  value:
                    debounce:
                      email: notavalid@nonexistent.tld
                      code: '3'
                      role: 'false'
                      free_email: 'false'
                      result: Invalid
                      reason: Undeliverable
                      send_transactional: '0'
                      did_you_mean: ''
                    success: '1'
                    balance: '329917'
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                debounce:
                  error: Wrong API
                  code: '0'
                success: '0'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                debounce:
                  error: Credits Low
                  code: '0'
                success: '0'
        '429':
          description: Too many requests or daily limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                concurrent_limit:
                  summary: Maximum concurrent calls reached
                  value:
                    debounce:
                      error: Maximum concurrent calls reached
                      code: '0'
                    success: '0'
                daily_limit:
                  summary: Daily limit reached
                  value:
                    debounce:
                      error: Authentication Failed - The maximum number of calls per day reached.
                    success: '0'
components:
  schemas:
    ValidationResult:
      type: object
      properties:
        email:
          type: string
          format: email
          description: The email address that was validated
        code:
          type: string
          description: 'DeBounce validation response code. See https://help.debounce.com/understanding-results/result-codes/ for details.

            '
        role:
          type: string
          enum:
          - 'true'
          - 'false'
          description: Whether the email is role-based (sales@, info@, webmaster@, etc.)
        free_email:
          type: string
          enum:
          - 'true'
          - 'false'
          description: Whether the email is from a free provider such as Gmail or Yahoo
        result:
          type: string
          enum:
          - Invalid
          - Risky
          - Safe to Send
          - Unknown
          description: The final validation result determining suitability for marketing emails
        reason:
          type: string
          description: The reason for the given result (e.g., Deliverable, Undeliverable, Catch-All)
        send_transactional:
          type: string
          enum:
          - '0'
          - '1'
          description: Whether sending transactional email to this address is recommended (1=yes, 0=no)
        did_you_mean:
          type: string
          description: Suggested corrected email address if a typo was detected
        photo:
          type: string
          format: uri
          description: Profile photo URL (only present if photo=true parameter was passed)
        name:
          type: string
          description: Full name associated with email (only present if append=true parameter was passed)
        avatar:
          type: string
          format: uri
          description: Avatar URL (only present if append=true parameter was passed)
    SingleValidationResponse:
      type: object
      properties:
        debounce:
          $ref: '#/components/schemas/ValidationResult'
        success:
          type: string
          enum:
          - '0'
          - '1'
          description: Whether the API call was successful (1) or not (0)
        balance:
          type: string
          description: Remaining credit balance after this call
    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
  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/.

        '