APIFreaks - API Hub for Developers Email Validation APIs API

openapi: 3.2.0
info:
  title: Apifreaks Api Hub For Developers Email Validation APIs API
  version: 1.0.0
  contact:
    name: APIFreaks Support
    url: https://apifreaks.com/contact
    email: support@apifreaks.com
  description: 'Operations tagged Email Validation APIs across 2 of this provider''s published API definitions: apifreaks-api-hub-for-developers-bulk-email-validation-openapi.json, apifreaks-api-hub-for-developers-email-checker-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.apifreaks.com/v1.0
  description: Bulk Email Validation API Server
security:
- ApiKeyAuthHeader: []
- ApiKeyAuthQuery: []
tags:
- name: Email Validation APIs
paths:
  /email-validation/bulk:
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: Bulk Email Validation API Server
    post:
      tags:
      - Email Validation APIs
      summary: Validate multiple email addresses
      description: Validates a bulk of email addresses and returns result for each. Maximum `100` email addresses per request.
      parameters:
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
          default: json
        description: Format of the response
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkEmailRequest'
      responses:
        '200':
          description: Successful response. Each item corresponds to one requested email, in the same order as the request; invalid emails are reflected via validEmail/validSyntax on that item, not as a separate error object — every item has success=true regardless of validation outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkEmailValidationResponse'
              examples:
                bulkEmailsValidated:
                  summary: Mix of a valid and a syntactically invalid email
                  value:
                    emailValidationResponses:
                    - success: true
                      email: abc.def@gmail.com
                      validEmail: valid
                      validSyntax: true
                      domain:
                        name: gmail.com
                        disposable: false
                        spam: false
                        free: true
                        validDomain: true
                        catchAll: false
                      account:
                        role: false
                        fullMailBox: false
                      dns:
                        mxRecords:
                        - gmail-smtp-in.l.google.com.
                        - alt1.gmail-smtp-in.l.google.com.
                        - alt2.gmail-smtp-in.l.google.com.
                        - alt3.gmail-smtp-in.l.google.com.
                        - alt4.gmail-smtp-in.l.google.com.
                    - success: true
                      email: not-an-email
                      validEmail: INVALID_EMAIL
                      validSyntax: false
                      domain:
                        name: not-an-email
                        validDomain: false
        '400':
          description: Bad Request – Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidBody:
                  summary: emailData field missing or malformed
                  value:
                    timestamp: '2026-07-27T12:53:14.628Z'
                    path: /v1.0/email-validation/bulk
                    status: 400
                    error: Invalid request body Exception
                    message: Please provide data in required format in request body
        '408':
          description: Request Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Request Timeout:
                  value:
                    timestamp: '2026-06-06T13:00:00.000Z'
                    path: /v1.0/email-validation/bulk
                    status: 408
                    error: Request Timeout
                    message: Timed out while connecting to the remote URL.
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Rate Limit Exceeded:
                  value:
                    timestamp: '2026-06-06T13:00:00.000Z'
                    path: /v1.0/email-validation/bulk
                    status: 429
                    error: Too Many Requests
                    message: API rate limit exceeded.
      operationId: bulkCheckEmail
  /email-validation/single:
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: Email Checker API Server
    post:
      tags:
      - Email Validation APIs
      summary: Validate a single email
      description: Validates a single email address and returns result.
      parameters:
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
        description: Format of the response
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailCheckRequest'
      responses:
        '200':
          description: Successful response with Email Validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleEmailValidationResponse'
              examples:
                validEmail:
                  summary: Valid, deliverable email
                  value:
                    success: true
                    email: abc.def@gmail.com
                    validEmail: valid
                    validSyntax: true
                    domain:
                      name: gmail.com
                      disposable: false
                      spam: false
                      free: true
                      validDomain: true
                      catchAll: false
                    account:
                      role: false
                      fullMailBox: false
                    dns:
                      mxRecords:
                      - gmail-smtp-in.l.google.com.
                      - alt1.gmail-smtp-in.l.google.com.
                      - alt2.gmail-smtp-in.l.google.com.
                      - alt3.gmail-smtp-in.l.google.com.
                      - alt4.gmail-smtp-in.l.google.com.
                invalidSyntax:
                  summary: Syntactically invalid email — domain/account/dns are minimal or absent
                  value:
                    success: true
                    email: not-an-email
                    validEmail: INVALID_EMAIL
                    validSyntax: false
                    domain:
                      name: not-an-email
                      validDomain: false
                noMxRecord:
                  summary: Valid syntax, domain has no MX record
                  value:
                    success: true
                    email: test@nonexistentdomainxyz123abc.com
                    validEmail: invalid
                    validSyntax: true
                    reason: mx record does not exist.
                    domain:
                      name: nonexistentdomainxyz123abc.com
                      disposable: false
                      spam: false
                      free: false
                      validDomain: false
                      catchAll: false
                    account:
                      role: false
                withIp:
                  summary: With ip — adds geolocation/security enrichment under address
                  value:
                    success: true
                    email: abc.def@gmail.com
                    validEmail: valid
                    validSyntax: true
                    domain:
                      name: gmail.com
                      disposable: false
                      spam: false
                      free: true
                      validDomain: true
                      catchAll: false
                    account:
                      role: false
                      fullMailBox: false
                    dns:
                      mxRecords:
                      - gmail-smtp-in.l.google.com.
                      - alt1.gmail-smtp-in.l.google.com.
                      - alt2.gmail-smtp-in.l.google.com.
                      - alt3.gmail-smtp-in.l.google.com.
                      - alt4.gmail-smtp-in.l.google.com.
                    ip: 8.8.8.8
                    address:
                      validIpAddress: true
                      location:
                        city: Mountain View
                        district: Santa Clara
                        confidence: low
                        zipcode: 94043-1351
                        state_prov: California
                        country_name: United States
                        continent_name: North America
                        continent_code: NA
                        country_code2: US
                        country_code3: USA
                        country_name_official: United States of America
                        accuracy_radius: '27.42'
                        is_eu: false
                      security:
                        threat_score: 5
                        is_tor: false
                        is_proxy: false
                        proxy_type: ''
                        proxy_provider: ''
                        is_anonymous: false
                        is_known_attacker: false
                        is_spam: false
                        is_bot: false
                        is_cloud_provider: true
                        cloud_provider: Google LLC
        '400':
          description: Bad Request – Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingEmail:
                  summary: email field missing from request body
                  value:
                    timestamp: '2026-07-27T12:51:23.593986185Z'
                    path: /v2.0/email-validation/single
                    status: 400
                    error: External API Error
                    message: Please pass valid value for 'email' in body.
        '408':
          description: Request Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Request Timeout:
                  value:
                    timestamp: '2026-06-06T13:00:00.000Z'
                    path: /v1.0/email-validation/single
                    status: 408
                    error: Request Timeout
                    message: Timed out while connecting to the remote URL.
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Rate Limit Exceeded:
                  value:
                    timestamp: '2026-06-06T13:00:00.000Z'
                    path: /v1.0/email-validation/single
                    status: 429
                    error: Too Many Requests
                    message: API rate limit exceeded.
      operationId: checkEmail
components:
  schemas:
    DnsObject:
      type: object
      required:
      - mxRecords
      properties:
        mxRecords:
          type: array
          items:
            type: string
          description: Collection of MX (Mail Exchange) hostname records from DNS queries.
        aRecords:
          type: array
          items:
            type: string
          description: Collection of A (Address) records for the domain. Not observed in testing — may be rarely or never populated.
      description: DNS records for the email domain.
    DomainObject:
      type: object
      required:
      - name
      - validDomain
      properties:
        name:
          type: string
          description: Extracted domain component from the email address.
        validDomain:
          type: boolean
          description: Domain validation status confirming DNS resolution capability.
        disposable:
          type: boolean
          description: Classification flag identifying domains from temporary email service providers.
        spam:
          type: boolean
          description: Reputation indicator flagging domains on spam databases.
        free:
          type: boolean
          description: Classification indicating free or consumer-grade email service providers.
        catchAll:
          type: boolean
          description: Detection flag for domains configured to accept mail for any recipient address.
      description: Domain validation details for the email address.
    BulkEmailValidationResponse:
      type: object
      description: Wrapper containing the per-email results array.
      required:
      - emailValidationResponses
      properties:
        emailValidationResponses:
          type: array
          description: Array of per-email results, one entry per requested email, in the same order as the request. Invalid emails are reflected via validEmail/validSyntax, not a separate error shape.
          items:
            $ref: '#/components/schemas/SingleEmailValidationResponse'
    BulkEmailRequest:
      type: object
      description: Request body for bulk email validation.
      required:
      - emailData
      properties:
        emailData:
          type: array
          description: Array of email objects to validate. Maximum 100 per request.
          maxItems: 100
          items:
            $ref: '#/components/schemas/BulkEmailRequestItem'
    SingleEmailValidationResponse:
      type: object
      required:
      - success
      - email
      - validEmail
      - validSyntax
      - domain
      properties:
        success:
          type: boolean
          description: 'Indicates the processing status of the validation request. true: completed successfully.'
        email:
          type: string
          format: email
          description: The email address submitted for validation.
        name:
          type: string
          description: Optional identifier or label provided in the request for record tracking.
        reason:
          type: string
          description: Detailed explanation returned when validEmail is not valid.
        validEmail:
          type: string
          enum:
          - valid
          - invalid
          - INVALID_EMAIL
          - unknown
          - risky
          description: 'Comprehensive deliverability assessment. Casing is inconsistent in the live API: syntactically invalid addresses return INVALID_EMAIL, while semantically invalid (undeliverable) addresses return lowercase invalid. unknown/risky are documented possibilities not observed during testing.'
        validSyntax:
          type: boolean
          description: Validates email address format compliance with RFC 5322 standards.
        domain:
          $ref: '#/components/schemas/DomainObject'
        account:
          $ref: '#/components/schemas/AccountObject'
        dns:
          $ref: '#/components/schemas/DnsObject'
        address:
          $ref: '#/components/schemas/AddressObject'
        ip:
          type: string
          format: ip
          description: IP address provided for geolocation and security enrichment.
      description: Email validation response containing deliverability assessment and metadata.
    ErrorResponse:
      type: object
      description: Standard error envelope returned by the API on failed requests.
      required:
      - message
      properties:
        error:
          type: string
          description: Short error category or exception type.
        message:
          type: string
          description: Human-readable error message describing the failure.
        path:
          type: string
          description: API endpoint path that produced the error.
        status:
          type: integer
          description: HTTP status code returned with the error.
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the error occurred (ISO 8601).
    EmailCheckRequest:
      type: object
      description: Request body for email validation.
      required:
      - email
      properties:
        email:
          type: string
          format: email
          description: Email address to validate.
        name:
          type: string
          description: Optional name or label for record tracking.
        ip:
          type: string
          format: ip
          description: Optional IP address for geolocation and security enrichment.
    EmailSecurity:
      type: object
      description: Threat and anonymity profile for the IP address.
      required:
      - threat_score
      - is_tor
      - is_proxy
      - proxy_type
      - proxy_provider
      - is_anonymous
      - is_known_attacker
      - is_spam
      - is_bot
      - is_cloud_provider
      - cloud_provider
      properties:
        threat_score:
          type: integer
          description: Quantitative risk assessment score. Higher values indicate elevated security risk.
        is_tor:
          type: boolean
          description: Detection flag for IP addresses routed through the Tor anonymity network.
        is_proxy:
          type: boolean
          description: Detection flag identifying IP addresses operating as proxy servers.
        proxy_type:
          type: string
          description: Classification of detected proxy infrastructure type (e.g. VPN, HTTP, SOCKS).
        proxy_provider:
          type: string
          description: Identified service provider operating the proxy infrastructure.
        is_anonymous:
          type: boolean
          description: Anonymization detection flag for IP addresses using identity obfuscation techniques.
        is_known_attacker:
          type: boolean
          description: Threat intelligence flag for IP addresses documented as confirmed malicious sources.
        is_spam:
          type: boolean
          description: Reputation flag for IP addresses associated with spam transmission.
        is_bot:
          type: boolean
          description: Automated traffic detection flag for IP addresses from bot networks.
        is_cloud_provider:
          type: boolean
          description: Infrastructure classification flag for IP addresses from cloud computing providers.
        cloud_provider:
          type: string
          description: Identified cloud infrastructure or hosting service provider name.
    EmailLocation:
      type: object
      description: Geolocation data derived from the IP address.
      properties:
        city:
          type: string
          description: Municipal or city name.
        district:
          type: string
          description: District or neighborhood.
        zipcode:
          type: string
          description: Postal or ZIP code.
        state_prov:
          type: string
          description: State or province.
        country_name:
          type: string
          description: Common country name.
        country_name_official:
          type: string
          description: Official country name.
        country_code2:
          type: string
          description: Two-character ISO country code.
        country_code3:
          type: string
          description: Three-character ISO country code.
        continent_name:
          type: string
          description: Continental region name.
        continent_code:
          type: string
          description: Continental region identifier.
        accuracy_radius:
          type: string
          description: Geolocation precision radius.
        confidence:
          type: string
          description: Confidence score for geolocation accuracy.
        is_eu:
          type: boolean
          description: European Union membership status.
      required: []
    AddressObject:
      type: object
      properties:
        validIpAddress:
          type: boolean
          description: IP recognized/reachable by the geolocation provider.
        location:
          $ref: '#/components/schemas/EmailLocation'
        security:
          $ref: '#/components/schemas/EmailSecurity'
      description: Geolocation and security enrichment data for the IP address.
      required: []
    BulkEmailRequestItem:
      type: object
      description: A single email entry in a bulk validation request.
      required:
      - email
      properties:
        email:
          type: string
          format: email
          description: Email address to validate.
        name:
          type: string
          description: Optional name or label.
        ip:
          type: string
          format: ip
          description: Optional IP address for enrichment.
    AccountObject:
      type: object
      required:
      - role
      properties:
        role:
          type: boolean
          description: Detection flag identifying role-based email addresses (e.g., admin@, support@).
        fullMailBox:
          type: boolean
          description: Storage capacity status indicator for the recipient mailbox.
      description: Account-level validation details.
  securitySchemes:
    ApiKeyAuthHeader:
      type: apiKey
      in: header
      name: X-apiKey
      description: Pass your API key via the X-apiKey request header.
    ApiKeyAuthQuery:
      type: apiKey
      in: query
      name: apiKey
      description: Pass your API key via the apiKey query parameter.
x-refined-from:
- apifreaks-api-hub-for-developers-bulk-email-validation-openapi.json
- apifreaks-api-hub-for-developers-email-checker-openapi.json