openapi: 3.1.0
info:
  title: MeterMaid — Email Checker-Plus API
  version: 1.0.0
  description: >
    One-call email verification: syntax validation (practical RFC 5322
    subset), disposable-domain detection against a bundled 121,570-entry
    open list (disposable-email-domains, MIT), role-account flagging, and
    MX existence via DNS-over-HTTPS with A-record fallback.
servers:
  - url: https://metermaid.square-firefly-0154.workers.dev
security:
  - ApiKey: []
paths:
  /v1/email/check:
    get:
      summary: Check one email address (GET)
      operationId: checkEmailGet
      parameters:
        - { name: email, in: query, required: true, schema: { type: string, format: email, example: person@example.com } }
      responses:
        '200':
          description: Check result (a syntactically invalid address is a 200 with valid=false)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EmailCheck' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/QuotaExceeded' }
    post:
      summary: Check one email address (POST)
      operationId: checkEmailPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email }
      responses:
        '200':
          description: Check result
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EmailCheck' }
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    QuotaExceeded:
      description: Plan quota exceeded
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Error:
      type: object
      properties:
        error: { type: string }
        message: { type: string }
    EmailCheck:
      type: object
      properties:
        email: { type: string }
        valid: { type: boolean, description: 'syntax ok, not disposable, MX found' }
        syntax_valid: { type: boolean }
        local_part: { type: string, nullable: true }
        domain: { type: string, nullable: true }
        is_disposable: { type: boolean }
        is_role_account: { type: boolean, description: 'admin@, support@, postmaster@, ...' }
        has_mx: { type: boolean }
        mx_records: { type: array, items: { type: string }, example: ['10 mx.example.com.'] }
        reason: { type: string, nullable: true, example: disposable_domain, description: 'first failure reason: empty | too_long | contains_whitespace | must_contain_exactly_one_at | local_part_length | local_part_characters | domain_length | domain_needs_a_dot | domain_label_characters | tld_too_short | disposable_domain | no_mx_records' }