Async Jobs and Polling

Find the job identifiers, status reads, terminal states, and polling rules for Brew email sends, automation runs, previews, and placement tests.

An accepted job has not necessarily finished or delivered an email. Keep its identifier and read its status until it reaches a terminal state.

Async Operations

Start work	Response identifier	Status read
POST /v1/automations/triggers/{triggerEventId}/fire	triggerInstanceId, automationRunIds[]	GET /v1/automations/trigger-instances/{triggerInstanceId} and GET /v1/automations/runs/{automationRunId}?include=logs
POST /v1/automations/{automationId}/test	automationRunIds[]	GET /v1/automations/runs/{automationRunId}?include=logs
POST /v1/automations/{automationId}/run	audienceRunId	GET /v1/automations/audience-runs/{audienceRunId}
POST /v1/sends (production)	sendId	GET /v1/sends/{sendId}
POST /v1/emails/{emailId}/client-previews	previewId	GET /v1/emails/client-previews/{previewId}
POST /v1/emails/{emailId}/inbox-placement-tests	testId	GET /v1/emails/{emailId}/inbox-placement-tests/{testId}
POST /v1/audiences/from-events	audienceId, build.jobId	GET /v1/audiences/{audienceId}?include=build

An automation dry run (dryRun: true) returns a synchronous preview instead of starting an audience run. An automation test omitting testRecipient sends no email; setting it delivers test copies to that address.

POST /v1/sends with test: true returns 200 { status: "completed", recipient } without a production send row. Production sends return 202 with queued, scheduled, or pending_approval; approval is required before a held send starts.

Fire a Trigger, Then Poll the Run

One trigger fire can start several published automations. Inspect every returned run ID. notStarted[] explains failed starts, and counts.skipped counts recipients covered by a suppression.

If no bound automation is published, the fire returns 422 NO_PUBLISHED_AUTOMATION and there are no runs to poll. Inspect the trigger instance to understand an accepted fire that returned no run IDs.

For a returned run ID:

export BREW_API_KEY="brew_your_api_key"
export AUTOMATION_RUN_ID="YOUR_RETURNED_RUN_ID"

curl --fail-with-body \
  "https://brew.new/api/v1/automations/runs/$AUTOMATION_RUN_ID?include=logs" \
  -H "Authorization: Bearer $BREW_API_KEY"

The response is the bare run, with status and logs at the top level. Organization keys also need X-Brand-Id; see Authentication.

Recommended Polling Cadence

For a short run, start with one read every two seconds and bound the wait to your application’s deadline. For flows with long wait nodes, read when you need an update. Avoid keeping a loop open for days.

Client previews provide nextPollAfterMs; honor it while work is pending. On 429, honor Retry-After. Budget all concurrent polls against the Rate Limits.

If your polling deadline expires, retain the job ID to inspect later.

Terminal States

Job	Finished states
Automation execution or manual-audience run	completed, failed, canceled
Production send	completed, partially_completed, failed, canceled
Client preview, inbox placement test, or audience build	completed, partially_completed, failed

scheduled, queued, running, and paused are not terminal. partially_completed means some work failed; inspect the result rather than treating it as full success.

Queue a Send, Then Verify

Read GET /v1/sends/{sendId} for delivery progress and aggregate stats. Add ?include=events for per-recipient events. Sending is complete before all later opens or clicks have occurred.

Monitor Email Sends owns the detailed monitoring workflow. Use Preview in Real Inboxes for rendering checks and the generated endpoint reference for placement-test schemas.

Idempotency on Async Retries

Once you have a job ID, poll it instead of submitting new work. If the starting request’s outcome is unknown, replay the same inputs with the same retry key. Idempotency owns the replay contract.

Raw HTTP and SDK email generation waits for the saved design or an explanatory response. MCP generation can return while the design is still generating; poll get_email with the returned IDs.

Cancel Instead of Waiting

Stop or control work	Route
One automation execution	POST /v1/automations/runs/{automationRunId}/cancel
A manual-audience run	POST /v1/automations/audience-runs/{audienceRunId}/{pause,resume,cancel}
A production send	POST /v1/sends/{sendId}/{pause,resume,cancel}

These actions cannot recall emails already delivered. Use the generated endpoint reference for action preconditions and response schemas.

Why No Webhooks Today

Outbound lifecycle webhooks remain on the roadmap. Polling is the supported way to follow these jobs today.

Need Help?

Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:

Self-Service Tools

Search Documentation

Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.

Ask ChatGPT or Claude

Click here to open the Copy page menu at the top of this page, then send the page to ChatGPT, Claude, or your editor.

Talk to Our Team

Schedule a Call

Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.

Call Us Directly

Need immediate assistance? Reach us at [phone] for urgent issues or time-sensitive questions.

Slack Channel

Our preferred support channel. You’ll receive an invite after signup for direct founder support and fast responses.

Email Support

Contact us at [e-mail] for detailed inquiries or if you prefer not to use Slack.