curl --request POST \
--url https://brew.new/api/v1/emails/{emailId}/inbox-placement-tests \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"domainId": "k57e9m3q1w8r"
}
'{
"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"
}{
"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"
}
}{
"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"
}
}
}{
"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"
}
}{
"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"
}
}{
"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"
}
}{
"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
}
}{
"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"
}
}{
"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
}
}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.
curl --request POST \
--url https://brew.new/api/v1/emails/{emailId}/inbox-placement-tests \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"domainId": "k57e9m3q1w8r"
}
'{
"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"
}{
"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"
}
}{
"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"
}
}
}{
"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"
}
}{
"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"
}
}{
"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"
}
}{
"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
}
}{
"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"
}
}{
"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
}
}Authorizations
Send your Brew API key as Authorization: Bearer brew_xxx.
Headers
Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.
1 - 100The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise 400 BRAND_ID_REQUIRED — there is no default brand); list ids with GET /v1/brands. Brand-scoped credentials may omit it, and sending a different brand returns 403 BRAND_SCOPE_MISMATCH. A brand outside your organization returns 404 BRAND_NOT_FOUND.
1 - 64Path Parameters
Design id returned by POST /v1/emails and listed by GET /v1/emails.
1 - 64"eml_2SmZOWV3ZQ7W5x6g3m4p"
Body
Verified sending domain id to test FROM (the seed send goes out on this domain, so the result reflects its real reputation).
1 - 64Subject 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.
1 - 200Preview/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.
200Pin a specific design version already available in the current surface; omit for the latest. A VARIANT dimension — test two versions of one design against each other.
1Restrict seed mailbox providers (e.g. ["gmail.com","outlook.com","yahoo.com"]); omit for a broad default spread.
1 - 30 elements1 - 80Response
The test was created and the seed send is in flight. Poll the GET endpoint for results.
pending, sending, collecting, completed, partial, failed x >= 0Show child attributes
Show child attributes
Show child attributes
Show child attributes
Was this page helpful?