verifly-email Verification API

openapi: 3.2.0
info:
  title: Verifly Email Verification 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: Verification
  description: Single, batch, and asynchronous bulk email verification.
paths:
  /api/v1/verify:
    get:
      tags:
      - Verification
      operationId: verifyEmail
      summary: Verify one email address
      description: Verify a single email address (deliverability, syntax, MX, SMTP, disposable, role, catch-all, free-provider). Costs one credit only when the upstream result is chargeable (credits_charged=true); catch-all/unknown results are commonly free (credits_charged=false).
      parameters:
      - name: email
        in: query
        required: true
        description: Email address to verify, for example lead@example.com.
        schema:
          type: string
          format: email
          maxLength: 254
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
              examples:
                undeliverable:
                  value:
                    success: true
                    email: test@gmail.com
                    is_valid: false
                    result: undeliverable
                    reason: Mailbox does not exist
                    details:
                      syntax_valid: true
                      domain_exists: true
                      mx_records: true
                      smtp_valid: false
                      is_disposable: false
                      is_role_account: true
                      is_catch_all: false
                      is_free_provider: true
                      provider: gmail.com
                    recommendation: do_not_send
                    credits_charged: true
                    credits:
                      used: 1
                      remaining: 99
                risky_catch_all:
                  value:
                    success: true
                    email: hello@example.com
                    is_valid: true
                    result: risky
                    reason: Catch-all server - cannot confirm individual address
                    details:
                      syntax_valid: true
                      domain_exists: true
                      mx_records: true
                      smtp_valid: false
                      is_disposable: false
                      is_role_account: true
                      is_catch_all: true
                      is_free_provider: false
                      provider: example.com
                    recommendation: risky
                    credits_charged: false
                    credits:
                      used: 0
                      remaining: 100
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-openai-isConsequential: true
  /api/v1/verify/batch:
    post:
      tags:
      - Verification
      operationId: verifyEmailBatch
      summary: Verify up to 100 email addresses synchronously
      description: Verify a batch of up to 100 emails synchronously. Invalid-format emails are NOT rejected for the whole request; they are placed in the skipped[] array (with skipped_count) alongside duplicates and any filtered addresses. Honors options.deduplicate (default true). Only successfully verified addresses appear in results[] and are charged.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailBatchRequest'
            examples:
              simple:
                value:
                  emails:
                  - lead@example.com
                  - sales@example.com
                  - bad-format
                  options:
                    deduplicate: true
      responses:
        '200':
          description: Batch results, skipped list, counts, and credit balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchVerificationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-openai-isConsequential: true
  /api/v1/verify/bulk:
    post:
      tags:
      - Verification
      operationId: createBulkVerificationJob
      summary: Create an asynchronous bulk verification job
      description: Submit a large email list (as emails[], raw text, or a multipart CSV file) for asynchronous verification. Returns a job with check_status_url / results_url / download_url. Small jobs may complete inline (status 'completed'); larger jobs return status 'pending'. Poll GET /api/v1/jobs/{id} for progress.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkVerificationRequest'
            examples:
              emails:
                value:
                  emails:
                  - lead1@example.com
                  - lead2@example.com
                  filename: leads.csv
                  webhook_url: https://example.com/verifly-webhook
              text:
                value:
                  text: 'lead1@example.com

                    lead2@example.com'
                  filename: paste.txt
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV file of emails.
                filename:
                  type: string
                webhook_url:
                  type: string
                  format: uri
      responses:
        '200':
          description: Bulk job accepted (pending) or completed inline.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkJobResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-openai-isConsequential: true
components:
  schemas:
    VerificationDetails:
      type: object
      properties:
        syntax_valid:
          type: boolean
        domain_exists:
          type: boolean
        mx_records:
          type: boolean
        smtp_valid:
          type: boolean
        is_disposable:
          type: boolean
        is_role_account:
          type: boolean
        is_catch_all:
          type: boolean
        is_free_provider:
          type: boolean
        provider:
          type: string
          description: Mail provider / domain.
      required:
      - syntax_valid
      - domain_exists
      - mx_records
      - smtp_valid
      - is_disposable
      - is_role_account
      - is_catch_all
      - is_free_provider
      - provider
    VerificationResult:
      type: object
      properties:
        success:
          type: boolean
        email:
          type: string
          format: email
          description: Normalized (lowercased/trimmed) email.
        email_original:
          type: string
          description: Present only when the input differed from the normalized email.
        is_valid:
          type:
          - boolean
          - 'null'
        result:
          type: string
          enum:
          - deliverable
          - undeliverable
          - risky
          - unknown
          description: Overall verdict.
        reason:
          type: string
          description: Human-readable explanation of the verdict.
        details:
          $ref: '#/components/schemas/VerificationDetails'
        recommendation:
          type: string
          enum:
          - safe_to_send
          - risky
          - do_not_send
        credits_charged:
          type: boolean
          description: True if this verification consumed a credit.
        credits:
          $ref: '#/components/schemas/Credits'
      required:
      - success
      - email
      - is_valid
      - result
      - reason
      - details
      - recommendation
      - credits_charged
      - credits
    BulkJobResult:
      type: object
      properties:
        success:
          type: boolean
        job_id:
          type: string
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
        total_emails:
          type: integer
          minimum: 0
        estimated_seconds:
          type: integer
          minimum: 0
        summary:
          $ref: '#/components/schemas/JobSummary'
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type: integer
          minimum: 0
        check_status_url:
          type: string
        results_url:
          type: string
        download_url:
          type: string
      required:
      - success
      - job_id
      - status
      - total_emails
      - check_status_url
      - results_url
      - download_url
    BulkVerificationRequest:
      type: object
      properties:
        emails:
          type: array
          minItems: 1
          maxItems: 1000000
          items:
            type: string
            maxLength: 254
        text:
          type: string
          description: Raw text/CSV to extract emails from when 'emails' is not provided.
        filename:
          type: string
          maxLength: 255
          default: bulk_upload.csv
        webhook_url:
          type: string
          format: uri
          description: Optional public HTTPS webhook called when the job completes.
      additionalProperties: false
    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
    BatchVerificationResult:
      type: object
      properties:
        success:
          type: boolean
        total:
          type: integer
        verified_count:
          type: integer
        skipped_count:
          type: integer
        valid_count:
          type: integer
        invalid_count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/BatchResultItem'
        skipped:
          type: array
          items:
            $ref: '#/components/schemas/SkippedEmail'
          description: 'Emails not verified: invalid format, duplicates, or filtered by options.'
        credits:
          $ref: '#/components/schemas/Credits'
      required:
      - success
      - total
      - verified_count
      - skipped_count
      - results
      - skipped
      - credits
    SkippedEmail:
      type: object
      properties:
        email:
          type: string
        reason:
          type: string
          description: e.g. invalid_format, duplicate, public_domain, role_account, disposable, blacklisted_domain, matched_pattern:<value>.
      required:
      - email
      - reason
    BatchResultItem:
      type: object
      properties:
        email:
          type: string
          format: email
        is_valid:
          type:
          - boolean
          - 'null'
        result:
          type: string
          enum:
          - deliverable
          - undeliverable
          - risky
          - unknown
        recommendation:
          type: string
          enum:
          - safe_to_send
          - risky
          - do_not_send
        reason:
          type: string
      required:
      - email
      - result
      - recommendation
    EmailBatchRequest:
      type: object
      required:
      - emails
      properties:
        emails:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
            maxLength: 254
        options:
          type: object
          properties:
            deduplicate:
              type: boolean
              default: true
            exclude_public_domains:
              type: boolean
              default: false
            exclude_role_accounts:
              type: boolean
              default: false
            domain_blacklist:
              type: array
              items:
                type: string
            pattern_blacklist:
              type: array
              items:
                type: string
          additionalProperties: false
    JobSummary:
      type: object
      properties:
        valid:
          type: integer
          minimum: 0
        invalid:
          type: integer
          minimum: 0
        risky:
          type: integer
          minimum: 0
    Credits:
      type: object
      properties:
        used:
          type: integer
          minimum: 0
          description: Credits charged by this request.
        remaining:
          type: integer
          minimum: 0
      required:
      - used
      - remaining
  responses:
    InsufficientCredits:
      description: Not enough Verifly credits to complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResult'
    RateLimited:
      description: Too many requests. Includes Retry-After (seconds) and the X-RateLimit-* headers.
      headers:
        Retry-After:
          schema:
            type: string
          description: Seconds to wait before retrying.
        X-RateLimit-Limit:
          schema:
            type: string
        X-RateLimit-Remaining:
          schema:
            type: string
        X-RateLimit-Reset:
          schema:
            type: string
          description: Unix epoch seconds when the limit window resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResult'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResult'
    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