ColdCapLimits

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/openmail-sh/json-schema/openmail-sh-cold-cap-limits-schema.json",
  "title": "ColdCapLimits",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/openmail-sh-openapi.json#/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",
            "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."
    }
  }
}