> ## Documentation Index > Fetch the complete documentation index at: https://docs.openmail.sh/llms.txt > Use this file to discover all available pages before exploring further. # Get cold outreach limits > 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. ## OpenAPI ````yaml https://api.openmail.sh/openapi.json get /v1/limits/cold openapi: 3.0.3 info: title: OpenMail 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: pods description: Isolated sub-accounts for your end users or tenants - name: inboxes description: Email inboxes and their webhook configuration - name: domains description: >- Custom domains: add your own sending/receiving domain, publish DNS, and verify it - name: owned-domains description: >- Domains your organisation controls but does not send from. Prove ownership with one TXT record and mail to their addresses stops counting toward the cold outreach limits. - name: messages description: Sending and listing messages - name: threads description: Conversation threads and read status - name: attachments description: Downloading and extracting text from attachments - name: policy description: >- Correspondent policy — provider-enforced allow/block rules and allowlist mode, scoped per account, pod, or inbox. Account-wide key only. - name: limits description: >- Sending limits: today's cold outreach caps on new recipients, per account, inbox, and domain, and what raises them - name: feedback description: Reporting bugs, friction, and feature requests to the OpenMail team paths: /v1/limits/cold: get: tags: - limits summary: Get cold outreach 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. operationId: getColdCapLimits 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: 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 description: Account-wide daily cap on new recipients. Null = no cap. nullable: true usedToday: type: integer remaining: type: integer nullable: true floor: type: integer description: Plan floor the cap never drops below while reputation is good. nullable: true ceiling: type: integer description: Plan ceiling the cap never exceeds. nullable: true 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 description: >- Share of recent cold threads that got a human reply. Null when the sample is too small to matter. nullable: true replySampleThreads: type: integer growthMultiplier: type: number description: >- How far above your 7-day average the cap may sit (2 = doubles weekly). sustainPerDayToGrow: type: integer description: >- Average more than this many new recipients per day over 7 days and the cap rises. Null when it cannot grow right now. nullable: true inbox: type: object 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 nullable: true 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 description: New recipients this domain may reach today. Null = no cap. nullable: true usedToday: type: integer remaining: type: integer nullable: true ageDays: type: integer description: Days since the domain was verified. lifetimeFirstContacts: type: integer description: New recipients ever emailed from this domain. nextTier: type: object description: >- What unlocks the next tier. Null when the domain already shares the account cap. properties: tier: type: integer limit: type: integer description: Daily cap on the next tier. Null = the account cap. nullable: true minAgeDays: type: integer minLifetimeFirstContacts: type: integer daysToGo: type: integer contactsToGo: type: integer nullable: true 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.' Error: type: object additionalProperties: true properties: error: type: string message: type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.