verifly-email Jobs API

openapi: 3.2.0
info:
  title: Verifly Email Verification Jobs 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: Jobs
  description: Asynchronous bulk verification job lifecycle (status, results, download, process).
paths:
  /api/v1/verify/bulk:
    post:
      tags:
      - Jobs
      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
  /api/v1/jobs:
    get:
      tags:
      - Jobs
      operationId: listJobs
      summary: List bulk verification jobs
      description: List the authenticated account's bulk verification jobs, newest first.
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: Paginated list of jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-openai-isConsequential: false
  /api/v1/jobs/{id}:
    get:
      tags:
      - Jobs
      operationId: getJob
      summary: Get bulk job status
      description: Get status and progress for a single bulk verification job.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Job status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-openai-isConsequential: false
  /api/v1/jobs/{id}/process:
    post:
      tags:
      - Jobs
      operationId: processJob
      summary: Trigger processing of a pending job
      description: 'Process (or continue processing) a pending bulk job. Auth: the API key that owns the job, OR an internal service key (X-Internal-Key header). Returns the number of emails processed in this pass.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Processing result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  processed:
                    type: integer
                    minimum: 0
                required:
                - success
                - processed
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-openai-isConsequential: true
  /api/v1/jobs/{id}/results:
    get:
      tags:
      - Jobs
      operationId: getJobResults
      summary: Get bulk job results as JSON
      description: Get the per-email verification results for a completed job as JSON.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Job results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-openai-isConsequential: false
  /api/v1/jobs/{id}/download:
    get:
      tags:
      - Jobs
      operationId: downloadJobResults
      summary: Download bulk job results as CSV
      description: 'Download the results of a completed job as a CSV attachment (columns: email, result, is_valid, recommendation, reason).'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'CSV file (Content-Disposition: attachment).'
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-openai-isConsequential: false
components:
  schemas:
    Job:
      type: object
      properties:
        success:
          type: boolean
        job_id:
          type: string
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
        progress:
          type: integer
          minimum: 0
          maximum: 100
        total_emails:
          type: integer
          minimum: 0
        processed:
          type: integer
          minimum: 0
        summary:
          $ref: '#/components/schemas/JobSummary'
        credits_used:
          type: integer
          minimum: 0
        file_name:
          type: string
        error_message:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        results_url:
          type:
          - string
          - 'null'
        download_url:
          type:
          - string
          - 'null'
      required:
      - success
      - job_id
      - status
    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
    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
    JobSummary:
      type: object
      properties:
        valid:
          type: integer
          minimum: 0
        invalid:
          type: integer
          minimum: 0
        risky:
          type: integer
          minimum: 0
    JobResults:
      type: object
      properties:
        success:
          type: boolean
        job_id:
          type: string
        total:
          type: integer
        summary:
          $ref: '#/components/schemas/JobSummary'
        credits_used:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/BatchResultItem'
      required:
      - success
      - job_id
      - results
    JobListResult:
      type: object
      properties:
        success:
          type: boolean
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        count:
          type: integer
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
        has_more:
          type: boolean
      required:
      - success
      - total
      - count
      - jobs
      - has_more
  responses:
    InsufficientCredits:
      description: Not enough Verifly credits to complete the request.
      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'
    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