> ## Documentation Index
> Fetch the complete documentation index at: https://developers.debounce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Email Validation

> Single email validation options and parameters

You can enhance single email validation results by enabling additional options in the request.

## Profile Photo

To include a profile photo (when available), add:

```
&photo=true
```

This option adds **1 extra credit** for each successful profile photo returned.

***

## Data Enrichment (Full Name & Avatar)

To retrieve enriched contact details such as the user’s full name and avatar, include:

```
&append=true
```

This option costs **20 extra credits** for each successful enrichment response.

***

<Warning>
  ### Important Usage Guidance

  When using this API on a **signup form**, the following statuses should be treated as valid:

  * **Deliverable**
  * **Accept-all**
  * **Unknown**

  This prevents rejecting legitimate new users.

  You may also rely on the `send_transactional` parameter:

  * If `send_transactional = 1`, the email is considered acceptable for user registration.
</Warning>


## OpenAPI

````yaml GET /v1/
openapi: 3.1.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: []
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'
components:
  schemas:
    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
    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'
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api
      description: API key for authentication

````