openapi: 3.0.3
info:
  title: Email Validator API
  version: 1.1.0
  description: |
    REST API for real-time SMTP email verification, bulk checks, email finder,
    and blacklist monitoring.

    **Authentication:** `X-API-Key` header (from your dashboard).

    **Credits:** Only `valid` and `invalid` results consume credits.
    `risky`, `catch_all`, `disposable`, `unknown`, and `spam_trap` are free.
  contact:
    url: https://email-validaton.com/contact
servers:
  - url: https://email-validaton.com/api/v1
    description: Production

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key from dashboard (ev_…)

  schemas:
    VerifyResult:
      type: object
      properties:
        email:
          type: string
          example: user@company.com
        status:
          type: string
          enum: [valid, invalid, risky, catch_all, disposable, spam_trap, unknown, error, rate_limited, out_of_credits]
        confidence:
          type: string
          enum: [high, medium, low, n/a]
        reason:
          type: string
        mx_server:
          type: string
        smtp_response:
          type: string
        source_ip:
          type: string
        duration_ms:
          type: integer
        remaining:
          type: integer
        is_role_account:
          type: boolean
        is_free_provider:
          type: boolean
        is_gibberish:
          type: boolean
        is_spam_trap:
          type: boolean
        cached:
          type: boolean
        scoring:
          type: object
          description: Present when scoring=true

    BulkRequest:
      type: object
      required: [emails]
      properties:
        emails:
          type: array
          maxItems: 50
          items:
            type: string
            format: email
        scoring:
          type: boolean
          default: false
        webhook_url:
          type: string
          format: uri
          description: HTTPS callback URL (optional)

    BulkResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/VerifyResult'
        summary:
          type: object
        remaining:
          type: integer
        count:
          type: integer
        webhook:
          type: string
          enum: [queued]

paths:
  /verify:
    get:
      summary: Verify single email (GET)
      parameters:
        - name: email
          in: query
          required: true
          schema:
            type: string
        - name: scoring
          in: query
          schema:
            type: boolean
        - name: webhook_url
          in: query
          schema:
            type: string
            format: uri
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResult'
    post:
      summary: Verify single email (POST)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                scoring:
                  type: boolean
                webhook_url:
                  type: string
                  format: uri
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResult'

  /bulk:
    post:
      summary: Bulk verify (up to 50 emails)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRequest'
      responses:
        '200':
          description: Bulk results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResponse'
        '400':
          description: Invalid request

  /finder:
    post:
      summary: Email finder (name + domain)
      description: |
        1 free search/month, then 5 credits per search (flat, whether found or not).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [first_name, last_name, domain]
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
                domain:
                  type: string
      responses:
        '200':
          description: Finder result

  /domain-pattern:
    get:
      summary: Known email format pattern for a domain
      description: |
        Returns cached pattern from Email Finder (e.g. `{first}.{last}`).
        Free — no credits consumed.
      parameters:
        - name: domain
          in: query
          required: true
          schema:
            type: string
            example: acme.com
      responses:
        '200':
          description: Pattern lookup result
          content:
            application/json:
              schema:
                type: object
                properties:
                  domain:
                    type: string
                  found:
                    type: boolean
                  pattern:
                    type: string
                    example: '{first}.{last}'
                  example:
                    type: string
                    example: john.smith@acme.com
                  is_catch_all:
                    type: boolean
                  last_seen:
                    type: string

  /blacklist/check:
    get:
      summary: DNSBL check for domain or IP
      parameters:
        - name: target
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Blacklist scan results

  /account:
    get:
      summary: Account info (plan, credits)
      responses:
        '200':
          description: Account details

  /credits:
    get:
      summary: Quick credit balance
      responses:
        '200':
          description: Credits remaining
