openmail-sh Limits API

openapi: 3.2.0
info:
  title: OpenMail Limits API
  description: Email infrastructure API for AI agents. Create inboxes, send and receive email, and get real-time notifications via webhooks.
  version: 1.0.0
  license:
    name: Proprietary
servers:
- url: https://api.openmail.sh
security:
- bearerAuth: []
tags:
- name: Limits
  description: 'Sending limits: today''s cold outreach caps on new recipients, per account, inbox, and domain, and what raises them'
paths:
  /v1/limits/cold:
    get:
      operationId: getColdCapLimits
      summary: Get cold outreach limits
      tags:
      - Limits
      description: 'Today''s caps on emailing **new recipients** — people who have never written to the inbox — and how much of each you have used. Returns the account cap, every verified custom domain''s warm-up tier and what unlocks the next one, and a `nextStep` sentence you can act on. Replies and follow-ups never count. Check this before a batch instead of discovering the cap through a 429.


        An inbox-scoped key sees the account cap plus its own inbox and domain. An account-wide key sees everything; pass `inboxId` to include that inbox''s per-inbox cap and only its domain.'
      parameters:
      - schema:
          type: string
        in: query
        name: inboxId
        required: false
        description: Include the per-inbox cap for this inbox and narrow `domains` to the one it sends from.
      responses:
        '200':
          description: Current cold outreach limits
          content:
            application/json:
              schema:
                description: Current cold outreach limits
                allOf:
                - $ref: '#/components/schemas/ColdCapLimits'
        '404':
          description: Inbox not found (`not_found`)
          content:
            application/json:
              schema:
                description: Inbox not found (`not_found`)
                allOf:
                - $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        message:
          type: string
    ColdCapLimits:
      type: object
      properties:
        mode:
          type: string
          enum:
          - reputation
          - legacy
          description: '`reputation`: caps count unique first-contacts and grow with your sending history. `legacy`: caps count every send to a never-inbound address and grow with account age.'
        unit:
          type: string
          enum:
          - new_recipients
          - never_inbound_sends
        resetsAt:
          type: string
          format: date-time
          description: When today's counters reset (midnight UTC).
        reputationState:
          type: string
          enum:
          - good
          - watch
          - throttled
          - suspended
        account:
          type: object
          properties:
            limit:
              type:
              - integer
              - 'null'
              description: Account-wide daily cap on new recipients. Null = no cap.
            usedToday:
              type: integer
            remaining:
              type:
              - integer
              - 'null'
            floor:
              type:
              - integer
              - 'null'
              description: Plan floor the cap never drops below while reputation is good.
            ceiling:
              type:
              - integer
              - 'null'
              description: Plan ceiling the cap never exceeds.
            coldStart:
              type: boolean
              description: True during the account's first week (or first 100 first-contacts).
            trustedVolume:
              type: boolean
              description: True when OpenMail has set a trusted volume for this account.
            avgNewPerDay7d:
              type: number
              description: Trailing 7-day average of new recipients per day.
            lifetimeFirstContacts:
              type: integer
            replyRate:
              type:
              - number
              - 'null'
              description: Share of recent cold threads that got a human reply. Null when the sample is too small to matter.
            replySampleThreads:
              type: integer
            growthMultiplier:
              type: number
              description: How far above your 7-day average the cap may sit (2 = doubles weekly).
            sustainPerDayToGrow:
              type:
              - integer
              - 'null'
              description: Average more than this many new recipients per day over 7 days and the cap rises. Null when it cannot grow right now.
        inbox:
          type:
          - object
          - 'null'
          description: Per-inbox cap, when one applies to the inbox this key is scoped to (or `inboxId` was passed).
          properties:
            id:
              type: string
            limit:
              type: integer
            usedToday:
              type: integer
            remaining:
              type: integer
        domains:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
              tier:
                type: integer
                description: Warm-up tier, 0 (newest) to 3 (shares the account cap). Matches the tier table in the docs.
              limit:
                type:
                - integer
                - 'null'
                description: New recipients this domain may reach today. Null = no cap.
              usedToday:
                type: integer
              remaining:
                type:
                - integer
                - 'null'
              ageDays:
                type: integer
                description: Days since the domain was verified.
              lifetimeFirstContacts:
                type: integer
                description: New recipients ever emailed from this domain.
              nextTier:
                type:
                - object
                - 'null'
                description: What unlocks the next tier. Null when the domain already shares the account cap.
                properties:
                  tier:
                    type: integer
                  limit:
                    type:
                    - integer
                    - 'null'
                    description: Daily cap on the next tier. Null = the account cap.
                  minAgeDays:
                    type: integer
                  minLifetimeFirstContacts:
                    type: integer
                  daysToGo:
                    type: integer
                  contactsToGo:
                    type: integer
              health:
                type: object
                description: Sending health of the inboxes on this domain over the last 7 days. `state` is the worst inbox's; rates are weighted by volume.
                properties:
                  state:
                    type: string
                    enum:
                    - good
                    - watch
                    - throttled
                    - suspended
                  volume7d:
                    type: integer
                    description: Emails sent from this domain's inboxes in the last 7 days.
                  bounceRate7d:
                    type: number
                  complaintRate7d:
                    type: number
        internalDomains:
          type: array
          description: 'Domains whose addresses never count as new recipients: your organisation''s own. Subdomains are covered. `source` says what proved it — `sending`: the registrable domain of a verified custom domain; `team`: a member signed in with an address on it; `txt`: verified via `POST /v1/owned-domains`.'
          items:
            type: object
            properties:
              domain:
                type: string
              source:
                type: string
                enum:
                - sending
                - team
                - txt
              via:
                type: string
                description: The sending domain, the login domain, or the owned-domain id.
        nextStep:
          type: string
          description: 'Plain-language summary: where you stand and what raises the cap.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key