Sign in

v1

latestOpenAPI 3.1.02026-07-2670105729.6 KB
Emails

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.

post/v1/emails/{emailId}/inbox-placement-tests

Path parameters

emailIdstring required

Design id returned by POST /v1/emails and listed by GET /v1/emails.

Example:eml_2SmZOWV3ZQ7W5x6g3m4p

Design id returned by POST /v1/emails and listed by GET /v1/emails.

Headers

Idempotency-Keystring

Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.

Request body

domainIdstring required

Verified sending domain id to test FROM (the seed send goes out on this domain, so the result reflects its real reputation).

subjectstring

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.

previewTextstring

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.

emailVersionIdstring

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.

providersstring[]

Restrict seed mailbox providers (e.g. ["gmail.com","outlook.com","yahoo.com"]); omit for a broad default spread.

Response

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

testIdstring required
emailIdstring required
status'pending' | 'sending' | 'collecting' | 'completed' | 'partial' | 'failed' required
domainIdstring required
subjectstring
previewTextstring
emailVersionIdstring
seedCountinteger required
errorMessagestring
createdAtstring required
updatedAtstring required