mailprobe-dev Account API

openapi: 3.2.0
info:
  title: MailProbe Account API
  version: 1.2.0
  description: 'Real-time email verification REST API, hosted in the EU (France, OVHcloud), GDPR-compliant. Every address is checked live — syntax, DNS MX lookup, SMTP handshake — and **no verification result is ever cached or stored**: each request re-probes and costs 1 credit per address actually probed.


    Authentication is by API key (`Authorization: Bearer mp_live_...`), created from the dashboard. Two endpoints: `POST /api/v1/verify` (1 to 20 addresses per call) and `GET /api/v1/credits`.


    Every result carries both the raw SMTP verdict (`result`) and an actionable rollup (`status`) plus a deterministic 0-100 `score`, so the scoring rubric is auditable rather than a black box.'
  termsOfService: https://mailprobe.dev/terms/
  contact:
    name: MailProbe
    url: https://mailprobe.dev/about/
servers:
- url: https://mailprobe.dev
  description: Production
security:
- bearerAuth: []
tags:
- name: Account
  description: Credit balance
paths:
  /api/v1/credits:
    get:
      tags:
      - Account
      summary: Check credit balance
      description: Returns the remaining credit balance. Credits are valid for 12 months from the most recent purchase; an expired balance returns `0`.
      operationId: getCredits
      responses:
        '200':
          description: Current balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credits'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    Unauthorized:
      description: Missing `Authorization` header, or a key that is not a valid `mp_live_...` (`UNAUTHORIZED`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: 'More than 60 requests per minute for this API key, or more than 300 requests per minute from the same IP address, all keys combined (`RATE_LIMITED`). Both limits count requests, not email addresses: a 20-address batch is one request. The response carries a `Retry-After` header: the number of seconds to wait before sending the request again. Standard `RateLimit-*` headers are returned.'
      headers:
        Retry-After:
          description: 'Number of seconds to wait before sending the request again: the time left until the limit resets.'
          required: true
          schema:
            type: integer
            example: 37
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable message.
        code:
          type: string
          description: Stable machine-readable code. Present on every error raised by the API handlers; absent on the two responses produced by the global error handler (413 and an unexpected 500).
          enum:
          - INVALID_INPUT
          - TOO_MANY
          - UNAUTHORIZED
          - NO_CREDITS
          - PAID_ONLY_DOMAIN
          - RATE_LIMITED
          - INTERNAL_ERROR
    Credits:
      type: object
      properties:
        credits:
          type: integer
          description: Credits remaining. `0` when the balance has expired.
          example: 847
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key in the `mp_live_...` format, created from the dashboard. Header: `Authorization: Bearer mp_live_...`.'