verifly-email Onboarding API

openapi: 3.2.0
info:
  title: Verifly Email Verification Onboarding 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: Onboarding
  description: Self-service agent registration. Get a first API key + free credits with no human.
paths:
  /api/v1/autonomous/register:
    post:
      tags:
      - Onboarding
      operationId: autonomousRegister
      summary: Self-register and get an API key (no human, 100 free credits)
      description: THE agent self-onboarding path. Creates an auto-confirmed account from {email, password} and returns a usable vf_ API key plus 100 free credits. No captcha, no email confirmation, no payment. Rate limited to 60 registrations per hour per IP (429 with Retry-After). The full api_key.key is shown ONCE and never again.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
            examples:
              agent:
                value:
                  email: my-agent@example.com
                  password: a-strong-password-8+
      responses:
        '200':
          description: Account created. Returns account + a one-time API key (api_key may be null in the rare case key generation fails after account creation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResult'
              examples:
                created:
                  value:
                    success: true
                    message: Account created successfully
                    account:
                      id: 676c92d0-0060-4c9a-af2a-cd64bc8fa720
                      email: my-agent@example.com
                      credits: 100
                    api_key:
                      key: vf_5U1y33fpfBkr1Hv3-XF4eawkSOpCnn8w-JMo84z94qQ
                      prefix: vf_5U1y33...
                      warning: Save this API key now. It will not be shown again.
        '400':
          description: invalid_email (bad email format) or invalid_password (too short, min 8 chars).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
        '409':
          description: email_exists - an account already uses this email.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-openai-isConsequential: true
components:
  schemas:
    RegisterRequest:
      type: object
      required:
      - email
      - password
      properties:
        email:
          type: string
          format: email
          maxLength: 254
        password:
          type: string
          minLength: 8
          description: Minimum 8 characters.
      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
    RegisterResult:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        account:
          type: object
          properties:
            id:
              type: string
              format: uuid
            email:
              type: string
              format: email
            credits:
              type: integer
              description: Free starting credits (100).
          required:
          - id
          - email
          - credits
        api_key:
          type:
          - object
          - 'null'
          description: Full key shown only once. Null only if account creation succeeded but key generation failed.
          properties:
            key:
              type: string
              description: Full vf_ API key. Store immediately.
            prefix:
              type: string
            warning:
              type: string
          required:
          - key
          - prefix
          - warning
      required:
      - success
      - message
      - account
      - api_key
  responses:
    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'
    ServerError:
      description: Internal server error. Credits are refunded on failed verification exceptions where possible.
      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