> ## Documentation Index > Fetch the complete documentation index at: https://docs.brew.new/llms.txt > Use this file to discover all available pages before exploring further. # Get domain health > The domain's deliverability health in one FREE read: a `verdict` (`healthy` / `at_risk` / `critical`) with actionable `signals`, DNS/auth state incl. DMARC, active percentage-based gradual sends + recent UTC-day volume, general bounce/complaint reporting, workspace reputation, and inbox-placement history. No bounce or complaint threshold is attached to a gradual-send configuration. ## OpenAPI ````yaml /api-reference/openapi-public-v1.yaml get /v1/domains/{domainId}/health openapi: 3.1.0 info: title: Brew Public API v1 version: 1.0.0 description: >- Generated from the Brew app Zod contracts (`lib//contracts.ts`). This file is the source of truth for the public API documentation. ## Resource paths Identity lives in the URL path (`/v1/analytics/sends/{sendId}`) — never in a query param or request body. Collections are plural top-level segments (`/v1/emails`); query params exist only for collection pagination + simple filters. Relationships are sub-resources (`/v1/emails/{emailId}/sends`), and non-CRUD operations are explicit action sub-paths (`/v1/automations/{automationId}/test`). ## Response envelopes - Lists: `{ data: Row[], pagination: { limit, cursor: string | null, hasMore } }` — loop `while (cursor !== null)`. - Get-one and writes: the bare resource (creates return `201`; async sends `202`). - Deletes: `{ , deleted: boolean }` — idempotent (already-gone ids resolve with `deleted: false`). - Errors: `{ error: { code, type, message, param?, suggestion, docs } }` — branch on the stable `code`. - ONE exception: `POST /v1/automations/triggers/{triggerEventId}/fire` responds with the legacy fire envelope `{ success, status, code, message, receivedAt, details }` (shared with internal webhook infrastructure). ## Brand scoping API keys are always scoped to a specific brand. The brand is resolved from the key on every request. **No public endpoint accepts a `brandId` field** in its request body or query string — sending one returns `400 INVALID_REQUEST`. Resources that exist in a different brand surface as `404` (never `403`), so the API does not leak cross-brand existence. `GET /v1/templates` is organization-wide and not constrained to the key brand. Brands themselves are managed in the Brew dashboard. ## Idempotency Send an `Idempotency-Key` header (≤ 100 chars) on any POST your code might retry. Same key + same body within 24h returns the original response; same key + different body returns `409 IDEMPOTENCY_CONFLICT`. contact: name: Brew Support url: https://docs.brew.new email: support@brew.new servers: - url: https://brew.new/api description: Production - url: http://localhost:3000/api description: Local development security: - bearerAuth: [] - apiKeyAuth: [] tags: - name: Emails description: >- Email designs and sending. Generate a design with the Brew email agent, edit, version, restore — then send it: `POST /v1/sends` delivers a design to a target (a saved audience, an inline list, or a single address) via a verified domain, and `POST /v1/sends/test` fires a one-off test. Sending is not campaign-specific. Send reads (list, status, per-send event feeds) live under Analytics (`/v1/analytics/sends`). - name: Analytics description: >- Read-only cross-resource analytics: lifetime per-campaign KPIs, windowed automation performance, the unified event feed, send reads (`/v1/analytics/sends`), and the fired-trigger audit log (`/v1/analytics/trigger-instances`). - name: Automations description: >- Automation graphs — deterministic create from explicit `nodes` + `connections`, update, version, publish / unpublish, test. Includes trigger event definitions + the fire endpoint (`/v1/automations/triggers`) and run history (`/v1/automations/runs`). - name: Contacts description: Create, search, patch, and delete contacts. Email is the primary key. - name: Contact Fields description: List, create, and delete custom contact field definitions. - name: Audiences description: Saved contact filter sets — a recipient target for sends. - name: Domains description: 'Sending domains: add, read DNS records, verify, configure sender defaults.' - name: Templates description: Public template gallery (read-only) usable as generation references. - name: Brand description: The single brand bound to the API key. - name: Chats description: >- Read a brand-scoped digest of a Brew chat — referenced emails/automations/triggers + a trimmed transcript — so an external agent can resume the conversation. - name: Meta description: >- Public discovery surface (no auth): the machine-readable API catalog (`/v1/help`). paths: /v1/domains/{domainId}/health: get: tags: - Domains summary: Get domain health description: >- The domain's deliverability health in one FREE read: a `verdict` (`healthy` / `at_risk` / `critical`) with actionable `signals`, DNS/auth state incl. DMARC, active percentage-based gradual sends + recent UTC-day volume, general bounce/complaint reporting, workspace reputation, and inbox-placement history. No bounce or complaint threshold is attached to a gradual-send configuration. operationId: getDomainHealth parameters: - schema: type: string minLength: 1 maxLength: 64 description: >- Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`. example: kx7bkh53hasmfeh5kd7sqgykt187g8ww required: true description: >- Domain id (opaque Convex document id) returned by `POST /v1/domains` and listed by `GET /v1/domains`. name: domainId in: path responses: '200': description: The aggregate health report. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. X-RateLimit-Limit: schema: type: integer description: Requests allowed in the current rolling rate limit window. example: 100 required: true description: Requests allowed in the current rolling rate limit window. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current rolling rate limit window. example: 99 required: true description: Requests remaining in the current rolling rate limit window. X-RateLimit-Reset: schema: type: integer description: >- Unix timestamp in seconds for when the rolling window fully resets. example: 1712592360 required: true description: >- Unix timestamp in seconds for when the rolling window fully resets. content: application/json: schema: $ref: '#/components/schemas/DomainHealth' example: domainId: kx7bkh53hasmfeh5kd7sqgykt187g8ww name: send.example.com status: verified sendable: true verdict: at_risk authentication: spf: verified dkim: verified dmarc: missing tracking: linksStatus: live openTracking: true clickTracking: true warmup: - sendId: snd_x1 currentTranche: 3 sentSoFar: 175 rampEndsAt: '2026-07-15T00:00:00.000Z' dailyVolume: - day: '2026-07-11T00:00:00.000Z' sent: 50 - day: '2026-07-12T00:00:00.000Z' sent: 63 domainActivity: sampled: true sampleSendCount: 12 sentCount: 2400 bouncedCount: 31 complainedCount: 1 bounceRate: 0.0129 complaintRate: 0.0004 orgReputation: scope: org totalSent: 18250 bounceRate: 0.011 complaintRate: 0.0003 recentPlacementTests: - testId: ibp_2f1c9d8a emailId: eml_welcome status: completed overall: total: 41 inbox: 33 spam: 8 missing: 0 pending: 0 authentication: spf: pass dkim: pass dmarc: pass spamFilterFlagged: false createdAt: '2026-07-13T17:00:00.000Z' signals: - id: dmarc_missing severity: warning summary: No DMARC record is configured for this domain. suggestion: >- Add a TXT record: _dmarc TXT "v=DMARC1; p=reject; rua=mailto:dmarc@send.example.com" — Gmail/Yahoo bulk-sender rules require DMARC, and it blocks spoofing. checkedAt: '2026-07-13T18:00:00.000Z' '401': description: The API key was missing, invalid, or revoked. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: INVALID_API_KEY type: authentication_error message: The provided API key is invalid. suggestion: Check the API key format and retry with a valid active key. docs: https://docs.brew.new/api-reference/api/authentication '403': description: The caller does not have the required `domains` permission. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: INSUFFICIENT_PERMISSIONS type: authorization_error message: The caller does not have the required permission. suggestion: Use an API key or session with the required permission. docs: https://docs.brew.new/api-reference/api/authentication param: domains '404': description: >- Domain not found in the API-key brand. Cross-brand ids intentionally surface as 404 (never 403) so the API does not leak cross-brand existence. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: DOMAIN_NOT_FOUND type: not_found message: The requested domain 'dom_xxx' was not found. suggestion: List domains with GET /v1/domains. docs: https://docs.brew.new/api-reference/api/errors param: domainId '429': description: The request hit the rolling rate limit window. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. X-RateLimit-Limit: schema: type: integer description: Requests allowed in the current rolling rate limit window. example: 100 required: true description: Requests allowed in the current rolling rate limit window. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current rolling rate limit window. example: 99 required: true description: Requests remaining in the current rolling rate limit window. X-RateLimit-Reset: schema: type: integer description: >- Unix timestamp in seconds for when the rolling window fully resets. example: 1712592360 required: true description: >- Unix timestamp in seconds for when the rolling window fully resets. Retry-After: schema: type: integer description: Seconds to wait before retrying the request. example: 42 required: true description: Seconds to wait before retrying the request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: RATE_LIMITED type: rate_limit message: Too many requests. suggestion: Wait for the retry window before sending another request. docs: https://docs.brew.new/api-reference/api/rate-limits retryAfter: 42 '500': description: Unexpected internal error. headers: x-request-id: schema: type: string description: >- Unique request identifier. Share this with support when debugging a request. example: req_8cac13fd94e6420cacdd75a1aa403a28 required: true description: >- Unique request identifier. Share this with support when debugging a request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: INTERNAL_ERROR type: internal_error message: An unexpected error occurred. suggestion: Retry the request. If it keeps failing, contact support. docs: https://docs.brew.new/api-reference/api/errors components: schemas: DomainHealth: type: object properties: domainId: type: string minLength: 1 maxLength: 64 name: type: string minLength: 1 maxLength: 253 status: type: string enum: - not_started - pending - verified - failed - temporary_failure - partially_verified - partially_failed sendable: type: boolean verdict: type: string enum: - healthy - at_risk - critical score: type: object properties: value: type: integer minimum: 0 maximum: 100 grade: type: string enum: - excellent - good - fair - poor - critical confidence: type: string enum: - high - medium - low components: type: object properties: placement: type: object properties: score: type: integer minimum: 0 maximum: 100 weight: type: number minimum: 0 maximum: 1 basis: type: string required: - score - weight - basis additionalProperties: false authentication: type: object properties: score: type: integer minimum: 0 maximum: 100 weight: type: number minimum: 0 maximum: 1 basis: type: string required: - score - weight - basis additionalProperties: false reputation: type: object properties: score: type: integer minimum: 0 maximum: 100 weight: type: number minimum: 0 maximum: 1 basis: type: string required: - score - weight - basis additionalProperties: false content: type: object properties: score: type: integer minimum: 0 maximum: 100 weight: type: number minimum: 0 maximum: 1 basis: type: string required: - score - weight - basis additionalProperties: false posture: type: object properties: score: type: integer minimum: 0 maximum: 100 weight: type: number minimum: 0 maximum: 1 basis: type: string required: - score - weight - basis additionalProperties: false required: - placement - authentication - reputation - content - posture additionalProperties: false trend: type: - object - 'null' properties: direction: type: string enum: - up - down - flat previousScore: type: integer minimum: 0 maximum: 100 previousComputedAt: type: string format: date-time required: - direction - previousScore - previousComputedAt additionalProperties: false required: - value - grade - confidence - components - trend additionalProperties: false authentication: type: object properties: spf: type: string enum: - verified - pending - failed - missing dkim: type: string enum: - verified - pending - failed - missing dmarc: type: string enum: - verified - pending - missing required: - spf - dkim - dmarc additionalProperties: false tracking: type: object properties: linksStatus: type: string enum: - live - no_cert - unreachable - unknown openTracking: type: boolean clickTracking: type: boolean additionalProperties: false warmup: type: array items: type: object properties: sendId: type: string currentTranche: type: integer sentSoFar: type: integer pausedAt: type: string pauseReason: type: string rampEndsAt: type: string required: - sendId additionalProperties: false dailyVolume: type: array items: type: object properties: day: type: string sent: type: integer minimum: 0 required: - day - sent additionalProperties: false domainActivity: type: - object - 'null' properties: sampled: type: boolean enum: - true sampleSendCount: type: integer minimum: 0 sentCount: type: integer minimum: 0 bouncedCount: type: integer minimum: 0 complainedCount: type: integer minimum: 0 bounceRate: type: number complaintRate: type: number required: - sampled - sampleSendCount - sentCount - bouncedCount - complainedCount - bounceRate - complaintRate additionalProperties: false orgReputation: type: - object - 'null' properties: scope: type: string enum: - org totalSent: type: integer minimum: 0 bounceRate: type: number complaintRate: type: number required: - scope - totalSent - bounceRate - complaintRate additionalProperties: false recentPlacementTests: type: array items: type: object properties: testId: type: string emailId: type: string status: type: string overall: type: - object - 'null' properties: total: type: integer minimum: 0 inbox: type: integer minimum: 0 spam: type: integer minimum: 0 missing: type: integer minimum: 0 pending: type: integer minimum: 0 required: - total - inbox - spam - missing - pending authentication: type: - object - 'null' properties: spf: type: string dkim: type: string dmarc: type: string additionalProperties: false spamFilterFlagged: type: boolean createdAt: type: string format: date-time required: - testId - emailId - status - overall - authentication - spamFilterFlagged - createdAt additionalProperties: false signals: type: array items: type: object properties: id: type: string enum: - domain_not_verified - dns_record_failed - dmarc_missing - sending_disabled - tracking_links_broken - high_bounce_rate - high_complaint_rate - placement_spam_heavy - content_spam_filter_flagged - auth_failing_in_tests - warmup_paused severity: type: string enum: - critical - warning - info summary: type: string suggestion: type: string action: type: object properties: tool: type: string note: type: string required: - tool additionalProperties: false required: - id - severity - summary - suggestion additionalProperties: false checkedAt: type: string format: date-time required: - domainId - name - status - sendable - verdict - score - authentication - tracking - warmup - dailyVolume - domainActivity - orgReputation - recentPlacementTests - signals - checkedAt additionalProperties: false ApiErrorEnvelope: type: object properties: error: type: object properties: code: type: string minLength: 1 type: type: string enum: - authentication_error - authorization_error - invalid_request - not_found - not_implemented - conflict - rate_limit - payment_required - service_unavailable - internal_error message: type: string minLength: 1 param: type: string minLength: 1 suggestion: type: string minLength: 1 docs: type: string format: uri retryAfter: type: integer minimum: 0 details: type: object additionalProperties: {} required: - code - type - message - suggestion - docs required: - error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: 'Send your Brew API key as `Authorization: Bearer brew_xxx`.' x-default: Bearer brew_your_api_key apiKeyAuth: type: apiKey in: header name: X-API-Key description: 'Send your Brew API key as `X-API-Key: brew_xxx`.' x-default: brew_your_api_key ````