verifly-email Billing API

openapi: 3.2.0
info:
  title: Verifly Email Verification Billing 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: Billing
  description: Credit packages and Stripe / crypto checkout. Agent-native crypto pay.
paths:
  /api/v1/billing:
    get:
      tags:
      - Billing
      operationId: getBilling
      summary: List credit packages or payment history
      description: action=packages (default) lists available credit packages. action=history lists the account's transactions.
      parameters:
      - name: action
        in: query
        required: false
        schema:
          type: string
          enum:
          - packages
          - history
          default: packages
      responses:
        '200':
          description: Packages or history.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PackagesResult'
                - $ref: '#/components/schemas/HistoryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-openai-isConsequential: false
    post:
      tags:
      - Billing
      operationId: createCheckout
      summary: Create a checkout to buy credits (Stripe or crypto)
      description: Create a payment to buy a credit package. method 'stripe' (default) returns a hosted Stripe checkout_url. method 'crypto' returns a Plisio invoice; when a 'currency' (BTC/ETH/LTC/USDT/USDC) is supplied the response also includes a RAW wallet address + amount + qr_code so an autonomous agent can pay from a wallet with no browser. This is the documented purchase path.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
            examples:
              stripe:
                value:
                  package_id: starter
                  method: stripe
              crypto:
                value:
                  package_id: pro
                  method: crypto
                  currency: USDT
      responses:
        '200':
          description: Checkout created.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/StripeCheckoutResult'
                - $ref: '#/components/schemas/CryptoCheckoutResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      x-openai-isConsequential: true
  /api/checkout:
    post:
      tags:
      - Billing
      operationId: createStripeCheckout
      summary: Create a Stripe checkout session (API key or session)
      description: 'Create a hosted Stripe checkout session for a credit package. Accepts an API key (Authorization: Bearer vf_...) OR a logged-in browser session. Body accepts package_id or packageId.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimpleCheckoutRequest'
            examples:
              buy:
                value:
                  package_id: starter
      responses:
        '200':
          description: Stripe session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleStripeResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      x-openai-isConsequential: true
  /api/checkout/crypto:
    post:
      tags:
      - Billing
      operationId: createCryptoCheckout
      summary: Create a crypto (Plisio) checkout (API key or session)
      description: Create a Plisio crypto invoice for a credit package. Accepts an API key OR a logged-in browser session. Body accepts package_id or packageId and an optional currency (BTC/ETH/LTC/USDT/USDC); when currency is supplied the response includes a raw wallet address + amount + qr_code.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimpleCryptoRequest'
            examples:
              buy:
                value:
                  package_id: starter
                  currency: BTC
      responses:
        '200':
          description: Crypto invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleCryptoResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      x-openai-isConsequential: true
components:
  schemas:
    CheckoutRequest:
      type: object
      required:
      - package_id
      properties:
        package_id:
          type: string
          enum:
          - starter
          - basic
          - pro
          - business
          - enterprise
        packageId:
          type: string
          description: Accepted alias of package_id.
        method:
          type: string
          enum:
          - stripe
          - crypto
          default: stripe
        currency:
          type: string
          enum:
          - BTC
          - ETH
          - LTC
          - USDT
          - USDC
          description: Only for method=crypto. When set, the response returns a raw wallet address + amount + qr_code.
    SimpleCryptoResult:
      type: object
      properties:
        success:
          type: boolean
        checkout_url:
          type: string
          format: uri
        url:
          type: string
          format: uri
          description: Backwards-compat alias of checkout_url.
        invoice_id:
          type: string
        address:
          type: string
        amount:
          type: string
        currency:
          type: string
          enum:
          - BTC
          - ETH
          - LTC
          - USDT
          - USDC
        qr_code:
          type: string
        expires_at:
          type: string
          format: date-time
        package:
          $ref: '#/components/schemas/PackageRef'
      required:
      - success
      - checkout_url
      - invoice_id
    PackagesResult:
      type: object
      properties:
        success:
          type: boolean
        packages:
          type: array
          items:
            $ref: '#/components/schemas/BillingPackage'
      required:
      - success
      - packages
    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
    SimpleStripeResult:
      type: object
      properties:
        success:
          type: boolean
        checkout_url:
          type: string
          format: uri
        url:
          type: string
          format: uri
          description: Backwards-compat alias of checkout_url.
        session_id:
          type: string
        package:
          $ref: '#/components/schemas/PackageRef'
      required:
      - success
      - checkout_url
    HistoryResult:
      type: object
      properties:
        success:
          type: boolean
        transactions:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              amount:
                type: number
              credits:
                type: integer
              status:
                type: string
              method:
                type: string
              date:
                type: string
                format: date-time
      required:
      - success
      - transactions
    BillingPackage:
      type: object
      properties:
        id:
          type: string
          enum:
          - starter
          - basic
          - pro
          - business
          - enterprise
        name:
          type: string
        credits:
          type: integer
        price:
          type: number
          description: Price in USD dollars.
        currency:
          type: string
          const: USD
        per_1k_credits:
          type: string
          description: Computed USD price per 1000 credits.
      required:
      - id
      - name
      - credits
      - price
      - currency
    SimpleCheckoutRequest:
      type: object
      required:
      - package_id
      properties:
        package_id:
          type: string
          enum:
          - starter
          - basic
          - pro
          - business
          - enterprise
        packageId:
          type: string
          description: Accepted alias of package_id.
    StripeCheckoutResult:
      type: object
      properties:
        success:
          type: boolean
        method:
          type: string
          const: stripe
        checkout_url:
          type: string
          format: uri
        session_id:
          type: string
        expires_at:
          type: string
          format: date-time
        package:
          $ref: '#/components/schemas/PackageRef'
      required:
      - success
      - checkout_url
    SimpleCryptoRequest:
      type: object
      required:
      - package_id
      properties:
        package_id:
          type: string
          enum:
          - starter
          - basic
          - pro
          - business
          - enterprise
        packageId:
          type: string
          description: Accepted alias of package_id.
        currency:
          type: string
          enum:
          - BTC
          - ETH
          - LTC
          - USDT
          - USDC
          description: When set, the response includes a raw wallet address + amount + qr_code.
    PackageRef:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        credits:
          type: integer
        price_usd:
          type: string
    CryptoCheckoutResult:
      type: object
      properties:
        success:
          type: boolean
        method:
          type: string
          const: crypto
        checkout_url:
          type: string
          format: uri
          description: Plisio invoice page.
        invoice_id:
          type: string
        address:
          type: string
          description: Raw wallet address (present when a currency was supplied).
        amount:
          type: string
          description: Crypto amount to send.
        currency:
          type: string
          enum:
          - BTC
          - ETH
          - LTC
          - USDT
          - USDC
        qr_code:
          type: string
          description: QR code (data URL or URL) for the payment address.
        expires_at:
          type: string
          format: date-time
        package:
          $ref: '#/components/schemas/PackageRef'
      required:
      - success
      - checkout_url
      - invoice_id
  responses:
    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