> ## 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. # Run an inbox placement test > Test where the design’s latest version LANDS — inbox vs spam vs missing — across real mailbox providers (Gmail, Outlook, Yahoo, Apple, …). Brew provisions a Mailgun seed list and sends the email to the seed addresses through your REAL send pipeline on a VERIFIED sending `domainId`, so the result reflects that domain’s true deliverability plus SPF/DKIM/DMARC. Returns immediately with a `testId` and `status: "collecting"`. Results accrue over a few minutes — poll `GET /v1/emails/{emailId}/inbox-placement-tests?testId=` until `status` is `completed`. This performs a real (small) send to the seeds IN ADDITION to the FIXED 10-credit test fee (`X-Credit-Cost: 10`), charged only on a 2xx. Requires a verified sending domain. ## OpenAPI ````yaml /api-reference/openapi-public-v1.yaml post /v1/emails/{emailId}/inbox-placement-tests 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/emails/{emailId}/inbox-placement-tests: post: tags: - Emails summary: Run an inbox placement test description: >- Test where the design’s latest version LANDS — inbox vs spam vs missing — across real mailbox providers (Gmail, Outlook, Yahoo, Apple, …). Brew provisions a Mailgun seed list and sends the email to the seed addresses through your REAL send pipeline on a VERIFIED sending `domainId`, so the result reflects that domain’s true deliverability plus SPF/DKIM/DMARC. Returns immediately with a `testId` and `status: "collecting"`. Results accrue over a few minutes — poll `GET /v1/emails/{emailId}/inbox-placement-tests?testId=` until `status` is `completed`. This performs a real (small) send to the seeds IN ADDITION to the FIXED 10-credit test fee (`X-Credit-Cost: 10`), charged only on a 2xx. Requires a verified sending domain. operationId: createInboxPlacementTest parameters: - name: Idempotency-Key in: header required: false description: >- Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours. schema: type: string minLength: 1 maxLength: 100 example: api-request-2026-04-08-001 - schema: type: string minLength: 1 maxLength: 64 description: >- Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`. example: eml_2SmZOWV3ZQ7W5x6g3m4p required: true description: >- Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`. name: emailId in: path requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EmailInboxPlacementRequest' examples: default: summary: Test a verified domain across all providers value: domainId: k57e9m3q1w8r targeted: summary: Restrict to specific providers + a custom subject value: domainId: k57e9m3q1w8r subject: March newsletter providers: - gmail.com - outlook.com - yahoo.com responses: '202': description: >- The test was created and the seed send is in flight. Poll the GET endpoint for results. 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/EmailInboxPlacementTest' example: testId: ibp_2f1c9d8a-4e77-4b0e-9a1c-6d5e2f0b7c31 emailId: eml_welcome status: collecting domainId: k57e9m3q1w8r seedCount: 42 results: null createdAt: '2026-07-13T17:00:06.675Z' updatedAt: '2026-07-13T17:00:06.675Z' '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 '402': description: >- The org's remaining credit balance is below what this operation requires. Credit cost is published PER-OPERATION (see `GET /v1/help`): content/media operations charge a flat cost, while AI generation (email generate/edit/import, image generation) is usage-metered — charged by actual model usage rather than a flat price. `details.cost` carries the amount the runtime required for THIS call. Check your balance up front via `GET /v1/usage`. No `Retry-After` — credits reset at the billing-period boundary. 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_CREDITS type: payment_required message: >- This operation required more credits than the 0 remaining on the 'free' plan. See the per-operation cost in GET /v1/help. suggestion: >- Upgrade your plan or wait for the next billing period to reset. Check your balance up front with GET /v1/usage. docs: https://docs.brew.new/api-reference/api/credits details: cost: 2 remaining: 0 planKey: free '403': description: The caller does not have the required `emails` 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: emails '404': description: >- No email exists with that id, or the domain is unknown (cross-brand ids surface as 404). 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: EMAIL_NOT_FOUND type: not_found message: No email exists with id 'eml_welcome'. suggestion: Verify the emailId via GET /v1/emails. docs: https://docs.brew.new/api-reference/api/errors '409': description: The same `Idempotency-Key` was reused with a different request body. 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: IDEMPOTENCY_CONFLICT type: conflict message: >- The same idempotency key was reused with a different request payload. suggestion: Reuse the original payload or send a new idempotency key. docs: https://docs.brew.new/api-reference/api/idempotency '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 '503': description: >- The credit balance could not be verified (a transient billing dependency outage). The gate fails closed rather than do paid work it cannot meter. Retryable — `Retry-After` indicates when. 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. 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: SERVICE_UNAVAILABLE type: service_unavailable message: >- Your credit balance could not be verified because a billing dependency is temporarily unavailable. suggestion: Retry the request after a short delay. docs: https://docs.brew.new/api-reference/api/credits retryAfter: 2 components: schemas: EmailInboxPlacementRequest: type: object properties: domainId: type: string minLength: 1 maxLength: 64 description: >- Verified sending domain id to test FROM (the seed send goes out on this domain, so the result reflects its real reputation). subject: type: string minLength: 1 maxLength: 200 description: >- Subject line for the seed send; defaults to the email title. A VARIANT dimension — run several tests on one design varying only the subject to compare placement. previewText: type: string maxLength: 200 description: >- Preview/preheader text for the seed send — overrides the design's JSX for this test. A VARIANT dimension, like `subject`: run several tests varying only the preheader to compare placement. emailVersionId: type: string minLength: 1 description: >- Pin a specific design version to test (from `list_email_designs` with `include: ["versions"]`); omit for the latest. A VARIANT dimension — test two versions of one design against each other. providers: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 30 description: >- Restrict seed mailbox providers (e.g. ["gmail.com","outlook.com","yahoo.com"]); omit for a broad default spread. required: - domainId additionalProperties: false EmailInboxPlacementTest: type: object properties: testId: type: string emailId: type: string status: type: string enum: - pending - sending - collecting - completed - partial - failed domainId: type: string subject: type: string previewText: type: string emailVersionId: type: string seedCount: type: integer minimum: 0 results: type: - object - 'null' properties: overall: type: object properties: provider: type: string 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 categories: type: object additionalProperties: type: integer minimum: 0 folders: type: object additionalProperties: type: integer minimum: 0 authentication: type: object properties: spf: type: string enum: - pass - fail - mixed dkim: type: string enum: - pass - fail - mixed dmarc: type: string enum: - pass - fail - mixed additionalProperties: false required: - provider - total - inbox - spam - missing - pending additionalProperties: false byProvider: type: array items: type: object properties: provider: type: string 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 categories: type: object additionalProperties: type: integer minimum: 0 folders: type: object additionalProperties: type: integer minimum: 0 authentication: type: object properties: spf: type: string enum: - pass - fail - mixed dkim: type: string enum: - pass - fail - mixed dmarc: type: string enum: - pass - fail - mixed additionalProperties: false required: - provider - total - inbox - spam - missing - pending additionalProperties: false authentication: type: object properties: spf: type: string dkim: type: string dmarc: type: string additionalProperties: false spamFilter: type: object properties: flagged: type: boolean score: type: number threshold: type: number rules: type: array items: type: object properties: name: type: string score: type: number description: type: string required: - name - score additionalProperties: false required: - flagged - score - threshold - rules additionalProperties: false microsoftFilter: type: object properties: spamConfidenceLevel: type: number bulkComplaintLevel: type: number sampleCount: type: integer minimum: 0 junked: type: boolean required: - spamConfidenceLevel - bulkComplaintLevel - sampleCount - junked additionalProperties: false spoofingDetected: type: boolean headers: type: object properties: listUnsubscribe: type: boolean oneClickUnsubscribe: type: boolean plainTextPart: type: boolean feedbackId: type: boolean required: - listUnsubscribe - oneClickUnsubscribe - plainTextPart - feedbackId additionalProperties: false required: - overall - byProvider - authentication additionalProperties: false diagnosis: type: array items: type: object properties: id: type: string enum: - spoofing_detected - aggregate_auth_failure - provider_auth_failure - microsoft_junk_filtering - provider_spam_placement - promotions_tab_placement - bulk_folder_placement - content_filter_flagged - content_rule - missing_list_unsubscribe - missing_plain_text_part severity: type: string enum: - critical - warning - info provider: type: string summary: type: string remediation: type: string required: - id - severity - summary - remediation additionalProperties: false errorMessage: type: string createdAt: type: string updatedAt: type: string required: - testId - emailId - status - domainId - seedCount - results - createdAt - updatedAt 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 ````