verifly-email Account API

openapi: 3.2.0
info:
  title: Verifly Email Verification Account 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: Account
  description: Account profile, credits, usage, and API key management.
paths:
  /api/v1/credits:
    get:
      tags:
      - Account
      operationId: getCreditBalance
      summary: Get credit balance
      description: Read the authenticated account's credit balance and usage today / this month. Read-only; agents use this to decide whether a workflow can continue.
      responses:
        '200':
          description: Credit balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditsResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-openai-isConsequential: false
  /api/v1/usage:
    get:
      tags:
      - Account
      operationId: getUsageSummary
      summary: Get API usage summary
      description: Read recent API usage for the authenticated account, including totals by endpoint/source, daily rollups, and recent rows.
      parameters:
      - name: period
        in: query
        required: false
        schema:
          type: string
          enum:
          - day
          - week
          - month
          default: month
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      responses:
        '200':
          description: Usage summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-openai-isConsequential: false
  /api/v1/account:
    get:
      tags:
      - Account
      operationId: getAccountProfile
      summary: Get account profile and credit summary
      description: Returns profile fields, credit balance, API key count, and usage totals for the API key owner.
      responses:
        '200':
          description: Account profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      x-openai-isConsequential: false
    patch:
      tags:
      - Account
      operationId: updateAccountProfile
      summary: Update account profile fields
      description: Updates account email, name, company, or timezone for the API key owner.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountUpdateRequest'
            examples:
              profile:
                value:
                  name: Avery Lee
                  company: Example Inc
                  timezone: America/Chicago
      responses:
        '200':
          description: Account updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUpdateResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      x-openai-isConsequential: true
  /api/v1/keys:
    get:
      tags:
      - Account
      operationId: listApiKeys
      summary: List API keys
      description: List the account's API keys (prefix only - full keys are never returned after creation).
      responses:
        '200':
          description: API keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyListResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-openai-isConsequential: false
    post:
      tags:
      - Account
      operationId: createApiKey
      summary: Create a new API key
      description: Create a new API key. The full key is returned ONCE in the 'key' field; store it immediately.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Optional friendly name.
            examples:
              named:
                value:
                  name: ci-pipeline
      responses:
        '200':
          description: Key created (full key shown once).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyCreateResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-openai-isConsequential: true
  /api/v1/keys/{id}:
    get:
      tags:
      - Account
      operationId: getApiKey
      summary: Get an API key
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Key metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  key:
                    $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-openai-isConsequential: false
    patch:
      tags:
      - Account
      operationId: renameApiKey
      summary: Rename an API key
      description: Rename an API key. Body {name} is required.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  maxLength: 255
            examples:
              rename:
                value:
                  name: production-key
      responses:
        '200':
          description: Key renamed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  key:
                    $ref: '#/components/schemas/ApiKey'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-openai-isConsequential: true
    delete:
      tags:
      - Account
      operationId: deleteApiKey
      summary: Revoke an API key
      description: Delete/revoke an API key. You cannot delete the key currently being used to authenticate the request.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Key deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-openai-isConsequential: true
components:
  schemas:
    KeyListResult:
      type: object
      properties:
        success:
          type: boolean
        count:
          type: integer
        keys:
          type: array
          items:
            $ref: '#/components/schemas/ApiKey'
      required:
      - success
      - count
      - keys
    AccountUpdateResult:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        updated:
          type: array
          items:
            type: string
      required:
      - success
      - message
      - updated
    KeyCreateResult:
      type: object
      properties:
        success:
          type: boolean
        key:
          type: string
          description: Full vf_ key, shown only once.
        message:
          type: string
        details:
          type: object
          properties:
            id:
              type: string
            name:
              type:
              - string
              - 'null'
            prefix:
              type: string
            created_at:
              type: string
              format: date-time
      required:
      - success
      - key
    AccountUpdateRequest:
      type: object
      minProperties: 1
      additionalProperties: false
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          maxLength: 255
        company:
          type: string
          maxLength: 255
        timezone:
          type: string
          example: America/Chicago
    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
    AccountProfile:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type:
          - string
          - 'null'
        company:
          type:
          - string
          - 'null'
        timezone:
          type: string
        credits:
          type: integer
          minimum: 0
        total_credits_used:
          type: integer
          minimum: 0
        api_keys_count:
          type: integer
          minimum: 0
        max_api_keys:
          type: integer
          minimum: 0
        plan:
          type: string
        is_corporate:
          type: boolean
        member_since:
          type: string
          format: date-time
    ApiKey:
      type: object
      properties:
        id:
          type: string
        prefix:
          type: string
        name:
          type:
          - string
          - 'null'
        active:
          type: boolean
        created_at:
          type: string
          format: date-time
        last_used_at:
          type:
          - string
          - 'null'
          format: date-time
    CreditsResult:
      type: object
      properties:
        success:
          type: boolean
        credits:
          type: integer
        used_today:
          type: integer
        used_this_month:
          type: integer
        plan:
          type: string
      required:
      - success
      - credits
      - used_today
      - used_this_month
      - plan
    MessageResult:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
      required:
      - success
      - message
    AccountResult:
      type: object
      properties:
        success:
          type: boolean
        account:
          $ref: '#/components/schemas/AccountProfile'
      required:
      - success
      - account
    UsageResult:
      type: object
      properties:
        success:
          type: boolean
        period:
          type: string
          enum:
          - day
          - week
          - month
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
        summary:
          type: object
          properties:
            total_credits_used:
              type: integer
            total_emails_processed:
              type: integer
            total_requests:
              type: integer
            by_endpoint:
              type: object
              additionalProperties:
                type: integer
            by_source:
              type: object
              additionalProperties:
                type: integer
        daily:
          type: array
          items:
            type: object
            additionalProperties: true
        recent:
          type: array
          items:
            type: object
            additionalProperties: true
      required:
      - success
      - period
      - start_date
      - end_date
      - summary
  responses:
    BadRequest:
      description: Invalid request or invalid input.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResult'
    NotFound:
      description: Resource not found or not owned by the authenticated account.
      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'
  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