mailboxlayer Verification API

openapi: 3.0.3
info:
  title: mailboxlayer Verification API
  description: 'The mailboxlayer API is a simple REST-based JSON API for thorough email address

    validation and verification. In addition to syntax checks, it performs real-time

    SMTP verification, MX-record lookup, catch-all detection, role-address detection,

    free-provider detection, disposable-provider detection, did-you-mean typo

    suggestions, and a numeric deliverability quality score.


    Authentication is via an API access key passed as the `access_key` query

    parameter. HTTPS is available on paid plans (Basic and above).

    '
  version: 1.0.0
  contact:
    name: mailboxlayer Customer Support
    email: support@apilayer.com
    url: https://mailboxlayer.com/support
  termsOfService: https://mailboxlayer.com/terms
  license:
    name: mailboxlayer Terms and Conditions
    url: https://mailboxlayer.com/terms
servers:
- url: https://apilayer.net/api
  description: HTTP endpoint (available on Free plan)
- url: https://apilayer.net/api
  description: HTTPS endpoint (available on Basic plan and above)
security:
- AccessKeyAuth: []
tags:
- name: Verification
  description: Email address validation and verification operations.
paths:
  /check:
    get:
      tags:
      - Verification
      summary: Verify Email Address
      description: 'Verifies a single email address. Performs syntax validation, MX-record

        lookup, SMTP verification (optional), catch-all detection, role-address

        detection, free-provider detection, disposable-provider detection,

        did-you-mean suggestion, and returns a deliverability quality score.

        '
      operationId: checkEmail
      parameters:
      - name: access_key
        in: query
        required: true
        description: Your mailboxlayer API access key.
        schema:
          type: string
          example: YOUR_ACCESS_KEY
      - name: email
        in: query
        required: true
        description: The email address to verify.
        schema:
          type: string
          format: email
          example: support@apilayer.net
      - name: smtp
        in: query
        required: false
        description: Set to `0` to skip the real-time SMTP check (default `1`).
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 1
      - name: format
        in: query
        required: false
        description: Set to `1` to pretty-print the JSON response (default `0`).
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
      - name: callback
        in: query
        required: false
        description: JSONP callback function name. Wraps the JSON response in a function call.
        schema:
          type: string
          example: myJsonpCallback
      responses:
        '200':
          description: Successful verification result. Note the API always returns 200 on a well-formed request; check the `success` field and `error.code` for failures.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CheckResult'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  summary: Successful verification
                  value:
                    email: support@apilayer.net
                    did_you_mean: ''
                    user: support
                    domain: apilayer.net
                    format_valid: true
                    mx_found: true
                    smtp_check: true
                    catch_all: false
                    role: true
                    disposable: false
                    free: false
                    score: 0.8
                typo:
                  summary: Did-you-mean suggestion
                  value:
                    email: support@apilayer.nt
                    did_you_mean: support@apilayer.net
                    user: support
                    domain: apilayer.nt
                    format_valid: true
                    mx_found: false
                    smtp_check: false
                    catch_all: null
                    role: true
                    disposable: false
                    free: false
                    score: 0.32
                invalid_email:
                  summary: Invalid email address error
                  value:
                    success: false
                    error:
                      code: 211
                      type: invalid_email_address
                      info: The email address supplied for the email parameter is invalid.
components:
  schemas:
    ErrorResponse:
      type: object
      description: Error response wrapper returned on a failed request.
      properties:
        success:
          type: boolean
          example: false
        error:
          $ref: '#/components/schemas/ApiError'
      required:
      - success
      - error
    ApiError:
      type: object
      properties:
        code:
          type: integer
          description: Numeric error code.
          enum:
          - 101
          - 103
          - 104
          - 105
          - 106
          - 210
          - 211
        type:
          type: string
          description: Machine-readable error identifier.
          enum:
          - invalid_access_key
          - invalid_api_function
          - usage_limit_reached
          - https_access_restricted
          - inactive_user
          - no_email_address_supplied
          - invalid_email_address
        info:
          type: string
          description: Human-readable error description.
      required:
      - code
      - type
      - info
    CheckResult:
      type: object
      description: Successful email verification result.
      properties:
        email:
          type: string
          format: email
          description: The email address submitted for verification.
        did_you_mean:
          type: string
          description: Suggested email address if a typo was detected, otherwise an empty string.
        user:
          type: string
          description: The local part (user) of the submitted email address.
        domain:
          type: string
          description: The domain part of the submitted email address.
        format_valid:
          type: boolean
          description: Whether the email address has a valid syntax.
        mx_found:
          type: boolean
          description: Whether MX records exist for the domain.
        smtp_check:
          type: boolean
          description: Whether the SMTP check succeeded (mailbox exists / SMTP server accepts the address).
        catch_all:
          type: boolean
          nullable: true
          description: Whether the domain is configured as catch-all. Available on paid plans.
        role:
          type: boolean
          description: Whether the address is a role-based address (e.g., `support@`, `admin@`).
        disposable:
          type: boolean
          description: Whether the domain belongs to a disposable email provider (e.g., `mailinator.com`).
        free:
          type: boolean
          description: Whether the domain belongs to a free email provider (e.g., `gmail.com`, `yahoo.com`).
        score:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Numeric quality score reflecting overall deliverability and quality (0.0 - 1.0).
      required:
      - email
      - user
      - domain
      - format_valid
      - mx_found
      - smtp_check
      - role
      - disposable
      - free
      - score
  securitySchemes:
    AccessKeyAuth:
      type: apiKey
      in: query
      name: access_key
      description: API access key provided when you sign up for a mailboxlayer plan.