Data Model

The entities behind Brew’s Public API v1, how they link, and what every identifier looks like, for builders joining sends, runs, and events.

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). Teammates’ open comment threads on it (commentId) hold messages (messageId).
• 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.
• Insight (insightId): one finding Brew Insights keeps about the brand’s email, with the frozen metrics behind it and the subject it is about, such as one send. See Read Brew Insights.

Identifiers

Identifier	Shape	Notes
emailId, emailVersionId	opaque, 21 chars (older designs: 36-char UUID)	The design and one persisted version of it. Returned by every generate, import, edit and restore.
automationId, automationVersionId	opaque, 21 chars	Stable across versions; liveAutomationVersionId is the version publish serves.
automationRunId	opaque, 32 lowercase alphanumerics	One per run of one automation for one recipient.
sendId	campaign: opaque 21 chars; automation per-recipient: as_ prefix; audience-run node: arn_ prefix	The analytics join key. kind on the row says which.
audienceRunId	arun_ prefix	One manual-audience launch of an automation.
triggerInstanceId	tin_ prefix, 4 to 64 chars	One inbound fire; GET /v1/automations/trigger-instances?triggerInstanceId= lists the runs it started.
triggerEventId	caller-supplied, up to 256 chars (a 21-char opaque id when omitted); integration triggers are composite provider:...	URL-encode composite ids in paths.
groupId	grp_ prefix, or the literal ungrouped	Email folders.
brandId, domainId, audienceId, keyId	opaque, 32 lowercase alphanumerics	audienceId also accepts the literal all on POST /v1/sends (every contact in the brand).
chatId	opaque, 21 chars	A Brew chat, for GET /v1/chats/{chatId}.
insightId	opaque, 32 lowercase alphanumerics	One finding of the insight engine, for GET /v1/insights/{insightId}; the app opens it at /insights/<insightId>.
commentId, messageId	cmt_ / cmm_ prefix, then 21 chars	A comment thread on a design and one message in it (GET /v1/emails/{emailId}/comments); the app opens a thread with ?commentId=.
notificationId	ntf_ + 20 lowercase hex chars	A notification (GET /v1/notifications): a one-way hash, stable for the row’s life. Response only.
uploadId	imgup_ + 21 chars	A local-file image upload from POST /v1/content/image-uploads, finished by POST /v1/content/add-image; expires after 15 minutes.
assetId	8 lowercase hex chars, derived from the asset URL	A logo or image of the brand library (GET /v1/brand/images); the app opens it at /assets?image=<assetId>.
email, fieldName	caller-defined	Contacts are keyed by address and custom fields by name; URL-encode in paths (jane%40example.com).
Idempotency-Key	caller-defined, up to 100 chars	Namespaced per organization server-side; 24-hour window.

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

• Pagination for the list envelope every collection shares.
• Errors for the *_NOT_FOUND code each identifier answers with.
• Migrate to the new v1 surface if you knew the pre-cleanup spellings.

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.

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to explore it further with ChatGPT or Claude.

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.