openmail-sh Limits API
Sending limits: today's cold outreach caps on new recipients, per account, inbox, and domain, and what raises them
Sending limits: today's cold outreach caps on new recipients, per account, inbox, and domain, and what raises them
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/openmail-sh:openmail-sh-limits-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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