---
title: "Run an inbox placement test"
method: POST
path: "/v1/emails/{emailId}/inbox-placement-tests"
tags: ["Emails"]
---

# Run an inbox placement test

`POST /v1/emails/{emailId}/inbox-placement-tests`

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.

## Path parameters

- `emailId` string, required — Design id returned by `POST /v1/emails` and listed by `GET /v1/emails`.

## Headers

- `Idempotency-Key` string

## Request body

- EmailInboxPlacementRequest
  - `domainId` string, required — Verified sending domain id to test FROM (the seed send goes out on this domain, so the result reflects its real reputation).
  - `subject` string — 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` string — Preview/preheader text for the seed send — overrides the design's JSX <Preview> for this test. A VARIANT dimension, like `subject`: run several tests varying only the preheader to compare placement.
  - `emailVersionId` string — 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` string[] — Restrict seed mailbox providers (e.g. ["gmail.com","outlook.com","yahoo.com"]); omit for a broad default spread.

## Response `202`

The test was created and the seed send is in flight. Poll the GET endpoint for results.

- EmailInboxPlacementTest
  - `testId` string, required
  - `emailId` string, required
  - `status` 'pending' | 'sending' | 'collecting' | 'completed' | 'partial' | 'failed', required
  - `domainId` string, required
  - `subject` string
  - `previewText` string
  - `emailVersionId` string
  - `seedCount` integer, required
  - `results` object, nullable, required
    - `overall` object, required
      - `provider` string, required
      - `total` integer, required
      - `inbox` integer, required
      - `spam` integer, required
      - `missing` integer, required
      - `pending` integer, required
      - `categories` object
      - `folders` object
      - `authentication` object
        - `spf` 'pass' | 'fail' | 'mixed'
        - `dkim` 'pass' | 'fail' | 'mixed'
        - `dmarc` 'pass' | 'fail' | 'mixed'
    - `byProvider` object[], required
      - `provider` string, required
      - `total` integer, required
      - `inbox` integer, required
      - `spam` integer, required
      - `missing` integer, required
      - `pending` integer, required
      - `categories` object
      - `folders` object
      - `authentication` object
        - `spf` 'pass' | 'fail' | 'mixed'
        - `dkim` 'pass' | 'fail' | 'mixed'
        - `dmarc` 'pass' | 'fail' | 'mixed'
    - `authentication` object, required
      - `spf` string
      - `dkim` string
      - `dmarc` string
    - `spamFilter` object
      - `flagged` boolean, required
      - `score` number, required
      - `threshold` number, required
      - `rules` object[], required
        - `name` string, required
        - `score` number, required
        - `description` string
    - `microsoftFilter` object
      - `spamConfidenceLevel` number, required
      - `bulkComplaintLevel` number, required
      - `sampleCount` integer, required
      - `junked` boolean, required
    - `spoofingDetected` boolean
    - `headers` object
      - `listUnsubscribe` boolean, required
      - `oneClickUnsubscribe` boolean, required
      - `plainTextPart` boolean, required
      - `feedbackId` boolean, required
  - `diagnosis` object[]
    - `id` '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', required
    - `severity` 'critical' | 'warning' | 'info', required
    - `provider` string
    - `summary` string, required
    - `remediation` string, required
  - `errorMessage` string
  - `createdAt` string, required
  - `updatedAt` string, required

## Other responses

- `401` — The API key was missing, invalid, or revoked.
- `402` — 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.
- `403` — The caller does not have the required `emails` permission.
- `404` — No email exists with that id, or the domain is unknown (cross-brand ids surface as 404).
- `409` — The same `Idempotency-Key` was reused with a different request body.
- `429` — The request hit the rolling rate limit window.
- `500` — Unexpected internal error.
- `503` — 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.

---

[API](https://skmtc.net/brew/apis/brew-public-api-v1.md) · [All operations](https://skmtc.net/brew/apis/brew-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/brew/brew-public-api-v1/versions/db96cfedc6c5/schema)