Brew’s two delivery primitives — campaign sends and automation runs — are asynchronous by design. The HTTP call accepts the work, persists an audit row, and returns a job identifier; the actual delivery happens on a durable Vercel Workflow runtime that retries, backs off, and emits per-step logs. This page covers the three async primitives, the canonical poll loop, and the agent-friendly recipes for concurrency.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.
Outbound webhooks for run / send / email-event lifecycle are on the roadmap. Until they ship, polling is the supported pattern. Both surfaces work today.
The three async primitives
| Primitive | Endpoint | Response | Poll with |
|---|---|---|---|
| Fire an automation | POST /v1/automation/runs (fire branch) | 202 { details: { automationRunIds: [...] } } | GET /v1/automation/runs?automationRunId=…&include=logs |
| Test an automation | POST /v1/automation/runs { mode: 'test' } | 202 { automationRunIds: [...], status: 'test_started' } | Same as fire |
| Send a campaign | POST /v1/sends | 202 { status: 'queued' | 'scheduled', runId, scheduledAt? } | Resend / send-job analytics in the dashboard today; webhook coming |
POST /v1/emails (AI generation) is also long-running (~30–90s) but blocks the HTTP call until the agent renders the JSX or refuses. It is not a job-returning async — you get the artifact back in the response.
Fire a trigger, then poll the run
Fire returns a list ofautomationRunIds (one per matched published automation). Each id is a workflow run you can inspect.
Recommended polling cadence
| Latency expectation | Cadence | Cap |
|---|---|---|
Welcome / transactional flow (single sendEmail node) | 2s × 60 | 2 min |
Multi-step drip with wait nodes (days) | Don’t poll — read the run when you actually need the answer (e.g. nightly cron) | n/a |
| QA / test fire | 1s × 30 | 30s |
automation.runs.read policy is 100/min per key. A 2-second poll is well under that for a handful of concurrent agents.
Queue a campaign send, then verify
POST /v1/sends returns 202 { status, runId, scheduledAt? }. The runId is the Vercel Workflow run id (correlated with delivery analytics on the dashboard).
Idempotency on async retries
Because retries are guaranteed-safe with idempotency keys, your agent / cron loop can re-fire the same operation without double-delivery. Same key + same body → sameautomationRunIds[], same runId, same response payload. See Idempotency for the full contract.
Agent concurrency patterns
Pattern 1 — fan out, fan in
An agent that runs 50 different welcome flows in parallel:automation.runs.write policy is 60/min. For 50 parallel fires, you’re well under; for 200+ you’d batch with Promise.allSettled + a 429-aware retry helper.
Pattern 2 — long-poll a single run to terminal
Use a generator so the agent can yield other work between polls:Pattern 3 — bulk inspect by automation
For dashboards / agents that want “the last 100 runs of this automation”:Why no webhooks today (and what’s next)
The fastest path to an A-gradeEvents & Streaming score is outbound webhooks; we’re shipping them. See the Webhooks & events page for the planned contract (webhook.run.completed, webhook.send.delivered, webhook.send.opened, …) and the roadmap. Until then, the poll loop on /v1/automation/runs is the supported way to wait for terminal status.
Endpoints that are already async-friendly
| Endpoint | Job indicator | Status read |
|---|---|---|
POST /v1/automation/runs (fire) | details.automationRunIds[] (one per matched automation) | GET /v1/automation/runs?automationRunId=… |
POST /v1/automation/runs { mode: 'test' } | automationRunIds[] | Same |
POST /v1/sends | runId (Vercel Workflow run id) | Analytics on the dashboard today; public read API roadmapped |
POST /v1/contacts (batch) | summary.{inserted,updated,failed} — synchronous | n/a |
See also
- Idempotency — pair with every async retry.
- Rate limits — keep your poll loop under
automation.runs.read(100/min). - Webhooks & events — inbound model today + outbound roadmap.
- Pagination — for bulk-inspecting runs.
- Agentic cookbook — end-to-end recipes built on these primitives.
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
- Talk to Our Team
Search Documentation
Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.
ChatGPT/Claude Integration
Click “Open in ChatGPT” at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.