Skip to main content
Every v1 resource hangs off an organization or one of its brands, and every row that one resource writes about another carries that other resource’s id. This page is the map: which entities exist, which id each one answers to, and how a fire, a run, a send, and its events join up. Per-endpoint request and response shapes live in the generated OpenAPI reference.

​
The Entity Map

Two entities are organization-wide: templates (a shared design, addressed by emailId) and usage. Everything else belongs to one brand. A brand-scoped API key names its brand implicitly; an organization-scoped key names it per call with X-Brand-Id. See Organization and brand scope.

​
What Each Entity Holds

  • Brand (brandId): the tenant every other row belongs to. It holds domains, contacts, audiences, designs, triggers, automations, and sends.
  • Domain (domainId): a verified sending domain. A send and every sendEmail node name the domain they deliver from.
  • Contact (email): one recipient with its core columns, customFields keyed by field name, and an optional consent record (source, capturedAt, policyVersion, evidence).
  • Field (fieldName): the definition behind a custom field, typed once per brand.
  • Audience (audienceId, or the literal all on a send for every subscribed contact): a saved filter over contacts. Launching a manual-audience automation against one produces an audience run (audienceRunId).
  • Email (emailId): a design and its versions (emailVersionId), filed under a group (groupId, or ungrouped).
  • Trigger (triggerEventId): a named event your systems fire. Its payload contract (contractHash, version, enforcement) validates each fire, and each fire is recorded as a trigger instance (triggerInstanceId) that lists the runs it started.
  • Automation (automationId): the graph, versioned (automationVersionId; liveAutomationVersionId is the version that runs). Each sendEmail node (nodeId) pins an emailId, an emailVersionId, and a domainId.
  • Automation run (automationRunId): one execution of one automation for one recipient. It carries the version it ran, its definitionHash, the triggerInstanceId that started it, and per-node logs.
  • Send (sendId): the unit of delivery. kind: campaign rows carry emailId, emailVersionId, domainId, and the audience or inline recipients. kind: automation rows add automationId, nodeId, and automationRunId, plus triggerInstanceId when a fire started the run or audienceRunId when a manual-audience launch did.
  • Event: one delivery or engagement event, stamped with the send, design, automation, node, run, fire, and audience run it belongs to.

​
Identifiers

Treat every identifier as opaque. Prefixes such as as_, arn_, arun_, tin_, and grp_ are stable, but they are not a contract to parse: the kind field on a send row says what kind of send it is.

​
From a Fire to an Inbox

The join keys above let you follow one event end to end:
  1. POST /v1/automations/triggers/{triggerEventId}/fire answers with a triggerInstanceId and the automationRunIds it started.
  2. GET /v1/automations/trigger-instances/{triggerInstanceId} shows the fire’s state and the same run ids; GET /v1/automations/runs/{automationRunId}?include=logs shows one run node by node.
  3. GET /v1/sends?automationRunId={automationRunId} lists that run’s per-recipient sends (kind: automation), each with its nodeId and triggerInstanceId.
  4. GET /v1/sends/{sendId}?include=events reads one send with its recipient events, and GET /v1/analytics/events?automationRunId={automationRunId} reads every event the run produced.
For a one-off campaign the chain is shorter: POST /v1/sends returns the sendId, GET /v1/sends?emailId={emailId} lists the sends of one design, and the same include=events read applies.

​
See Also

​
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:

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 explore it further with ChatGPT or Claude.