verifly-email Tools API

openapi: 3.2.0
info:
  title: Verifly Email Verification Tools API
  version: 2.0.0
  description: 'Pay-as-you-go email verification API for developers, SaaS products, signup validation, bulk email list cleaning, CSV workflows, and AI agents. Verifly verifies deliverability, cleans lists, extracts emails from text, detects risky/disposable/role addresses, checks domain DNS health, and exposes usage/credit/billing endpoints.


    AGENT SELF-ONBOARDING: An autonomous agent can get a working API key with NO human, captcha, or payment by calling POST /api/v1/autonomous/register with an email + password. It returns a vf_ API key and 100 free credits (auto-confirmed). Use that key as ''Authorization: Bearer vf_...'' on every /api/v1 endpoint.


    PURCHASING (agent-native): POST /api/v1/billing with method ''crypto'' and a currency (BTC/ETH/LTC/USDT/USDC) returns a raw wallet address + amount + QR so an agent can top up credits from a wallet with no browser.


    RATE LIMITS: Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers; 429 responses also include Retry-After (seconds).'
  contact:
    name: Verifly Support
    email: hello@veriflyemail.com
    url: https://verifly.email/docs
  termsOfService: https://verifly.email/terms
servers:
- url: https://verifly.email
  description: 'Production API. All /api/v1/* paths require Authorization: Bearer vf_<key>.'
security:
- bearerAuth: []
tags:
- name: Tools
  description: Public utility endpoints such as domain DNS health.
paths:
  /api/tools/domain-health:
    get:
      tags:
      - Tools
      operationId: domainHealth
      summary: Check a domain's email DNS health (MX/SPF/DMARC)
      description: 'Public endpoint (no API key required). Returns a 0-100 health score plus MX, SPF, and DMARC findings for a domain. Note: this lives under /api/tools, NOT /api/v1.'
      security: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          type: string
        description: Domain to check, e.g. example.com. Provide either domain or email.
      - name: email
        in: query
        required: false
        schema:
          type: string
          format: email
        description: Email whose domain will be checked.
      responses:
        '200':
          description: Domain health report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainHealthResult'
              examples:
                google:
                  value:
                    domain: google.com
                    score: 100
                    mx:
                    - exchange: smtp.google.com
                      priority: 10
                    spf:
                      found: true
                      count: 1
                      records:
                      - v=spf1 include:_spf.google.com ~all
                    dmarc:
                      found: true
                      policy: reject
                      records:
                      - v=DMARC1; p=reject; rua=mailto:mailauth-reports@google.com
                    txtLookup:
                      rootError: ''
                      dmarcError: ''
                    warnings: []
                    checkedAt: '2026-06-27T07:30:44.726Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
      x-openai-isConsequential: false
components:
  schemas:
    ErrorResult:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable code, e.g. invalid_email, invalid_password, email_exists, invalid_api_key, invalid_package, invalid_currency, invalid_method, insufficient_credits, rate_limit_exceeded.
            message:
              type: string
            suggestion:
              type: string
          required:
          - code
          - message
      required:
      - success
      - error
    DomainHealthResult:
      type: object
      properties:
        domain:
          type: string
        score:
          type: integer
          minimum: 0
          maximum: 100
        mx:
          type: array
          items:
            type: object
            properties:
              exchange:
                type: string
              priority:
                type: integer
            required:
            - exchange
            - priority
        spf:
          type: object
          properties:
            found:
              type: boolean
            count:
              type: integer
            records:
              type: array
              items:
                type: string
        dmarc:
          type: object
          properties:
            found:
              type: boolean
            policy:
              type: string
              description: none|quarantine|reject (empty when not found).
            records:
              type: array
              items:
                type: string
        txtLookup:
          type: object
          properties:
            rootError:
              type: string
            dmarcError:
              type: string
        warnings:
          type: array
          items:
            type: string
        checkedAt:
          type: string
          format: date-time
      required:
      - domain
      - score
      - mx
      - spf
      - dmarc
  responses:
    ServerError:
      description: Internal server error. Credits are refunded on failed verification exceptions where possible.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResult'
    BadRequest:
      description: Invalid request or invalid input.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResult'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Verifly API key
      description: 'Use ''Authorization: Bearer vf_your_api_key''. Get a key with no human via POST /api/v1/autonomous/register. Never expose API keys in prompts, logs, screenshots, client-side code, or public examples.'
externalDocs:
  description: Verifly API docs
  url: https://verifly.email/docs
x-agent-guidance:
  selfOnboarding: 'POST /api/v1/autonomous/register {email,password} -> returns a vf_ API key + 100 free credits, no human/captcha/payment. Use it as ''Authorization: Bearer vf_...''.'
  buyCredits: POST /api/v1/billing {package_id, method:'crypto', currency:'USDT'} returns a raw wallet address + amount + qr_code for browserless payment; or method:'stripe' for a hosted checkout_url.
  useWhen:
  - email verification API
  - bulk email list cleaning
  - signup validation
  - disposable/role/catch-all email detection
  - domain MX/SPF/DMARC health check
  - AI agent email hygiene
  - ChatGPT email verification action
  safety:
  - Do not expose API keys.
  - Do not invent verification results.
  - Ask before processing private or large email lists.
  - Verifly verifies and cleans lists; it does not send outreach emails.
  mcp:
    name: verifly-mcp-server
    install: npx verifly-mcp-server
    env: VERIFLY_API_KEY
    hosted: https://verifly.email/mcp
    transport: Streamable HTTP (POST)
    github: https://github.com/james-sib/verifly-mcp-server
    tools:
    - verify_email
    - verify_batch
    - clean_email_list
    - extract_emails
    - check_domain_health
    - get_credits
  chatgptAction: https://verifly.email/chatgpt-action-openapi.json
  cli: https://verifly.email/cli