openapi: 3.2.0
info:
  title: DeBounce Email Validation API
  description: Single email validation, reverse lookup, balance, and usage endpoints.
  license:
    name: MIT
  version: 1.0.0
servers:
- url: https://api.debounce.io
security:
- ApiKeyQuery: []
tags:
- name: DeBounce Email Validation API
paths:
  /v1/:
    get:
      summary: Validate Single Email Address
      description: Validates a single email address and returns detailed validation results
      operationId: validateEmail
      parameters:
      - name: api
        in: query
        required: true
        schema:
          type: string
          example: API_KEY
        description: Your DeBounce API key
      - name: email
        in: query
        required: true
        schema:
          type: string
          format: email
        description: The email address you want to validate
      - name: photo
        in: query
        required: false
        schema:
          type: boolean
        description: If set to true, returns profile photo (extra credits apply)
      - name: append
        in: query
        required: false
        schema:
          type: boolean
        description: If set to true, enriches with full name and avatar (extra credits apply)
      - name: gsuite
        in: query
        required: false
        schema:
          type: boolean
        description: If set to true, detects G Suite accept-all emails
      responses:
        '200':
          description: Validation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
              examples:
                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'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                debounce:
                  error: Wrong API
                  code: '0'
                success: '0'
        '402':
          description: Credits Low
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                debounce:
                  error: Credits Low
                  code: '0'
                success: '0'
        '429':
          description: Too Many Requests / Daily Limit Reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tooManyRequests:
                  summary: Too many concurrent calls
                  value:
                    debounce:
                      error: Maximum concurrent calls reached
                      code: '0'
                    success: '0'
                dailyLimit:
                  summary: Daily limit reached (Public API key)
                  value:
                    debounce:
                      error: Authentication Failed - The maximum number of calls per day reached.
                    success: '0'
      tags:
      - DeBounce Email Validation API
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        message:
          type: string
        debounce:
          type: object
          properties:
            error:
              type: string
            code:
              type: string
        success:
          type: string
          enum:
          - '0'
    ValidationResult:
      type: object
      required:
      - email
      - result
      - success
      properties:
        email:
          description: The email address you are requesting to validate.
          type: string
          format: email
          example: test@example.com
        code:
          description: DeBounce validation response code. To understand DeBounce results and codes, visit https://help.debounce.com/understanding-results/result-codes/.
          type: integer
          example: 1
        role:
          description: Is the email role-based or not. Role emails such as "sales@", "webmaster@" etc., are not suitable for sending marketing emails to.
          type: boolean
          example: false
        free_email:
          description: Is the email from a free email provider - like Gmail - or not.
          type: boolean
          example: true
        result:
          description: The final result of the validation process. This response will help to determine whether you should send marketing emails to a recipient or not.
          type: string
          enum:
          - Invalid
          - Risky
          - Safe to Send
          - Unknown
          example: Safe to Send
        reason:
          description: The reason why the result is given.
          type: string
          example: Deliverable
        send_transactional:
          description: 'Is it suggested that you send transactional emails to the recipient or not (0: no, 1: yes).'
          type: integer
          enum:
          - 0
          - 1
          example: 1
        did_you_mean:
          description: Suggested corrected email when a typo is detected.
          type: string
          example: ''
        success:
          description: 'Is your call successful or not (0: no, 1: yes).'
          type: integer
          enum:
          - 0
          - 1
          example: 1
        balance:
          description: Remaining balance on your account after the current API call.
          type: integer
          example: 4921
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api
      description: API key for authentication