Explore Per-Contact Engagement

GET /v1/analytics/events is a unified event feed across four domains: email, automation, trigger, and inbound. Filter by recipient to get one contact’s complete engagement timeline, or by eventType / automationId / sendId to slice the whole brand. Requires the emails scope. Every delivery event attaches to the sendId it came from, so you can also scope the feed to a single send: pass ?sendId= here, or read that send with GET /v1/sends/{sendId}?include=events for a bounded first page on the row itself. See Monitor campaign sends. When from/to are omitted the API defaults to the last 7 days. The response carries { data, pagination, range }.

One Contact’s Timeline

curl -G "https://brew.new/api/v1/analytics/events" \
  -H "Authorization: Bearer $BREW_API_KEY" \
  --data-urlencode "recipient=jane@example.com" \
  --data-urlencode "limit=100"

import { createBrewClient } from '@brew.new/sdk'

const brew = createBrewClient({ apiKey: process.env.BREW_API_KEY! })

const { data, range } = await brew.analytics.events({
  recipient: 'jane@example.com',
})
for (const event of data) {
  console.log(event.occurredAt, event.domain, event.eventType, event.emailName)
}

Export a Full Timeline

The SDK auto-pager walks every page so you never touch the cursor:

const timeline = []
for await (const event of brew.analytics.eventsAll({
  recipient: 'jane@example.com',
  from: '2026-01-01T00:00:00.000Z',
})) {
  timeline.push(event)
}

Filter by Event Type or Automation

// Every bounce in the brand over the last 7 days
const { data: bounces } = await brew.analytics.events({ eventType: 'bounced' })

// Everything that happened inside one automation
const { data: runEvents } = await brew.analytics.events({
  automationId: 'auto_welcome',
})

// Every event from one campaign send
const { data: sendEvents } = await brew.analytics.events({
  sendId: 'snd_8fK2mQ4p',
})

The filter is recipient; the row field it matches is recipientEmail. Each EventRow carries domain, eventType, recipientEmail?, sendId?, emailId?/emailName?, automationId?/automationName?, nodeId?, mode? (live | test), and a human summary?.

Count Events Instead of Listing Them

Add groupBy, bucket, or both to count the email events the same filters list instead of returning them. groupBy takes one or two comma-separated fields: eventType, emailId, automationId, sendId, source, link, recipientDomain, unsubscribeReason. bucket takes day, week or month (UTC; weeks start Monday).

# Clicks per link on one send
curl -G "https://brew.new/api/v1/analytics/events" \
  -H "Authorization: Bearer $BREW_API_KEY" \
  --data-urlencode "sendId=snd_8fK2mQ4p" \
  --data-urlencode "eventType=clicked" \
  --data-urlencode "groupBy=link"

# Email events per type per day since September 1
curl -G "https://brew.new/api/v1/analytics/events" \
  -H "Authorization: Bearer $BREW_API_KEY" \
  --data-urlencode "groupBy=eventType" \
  --data-urlencode "bucket=day" \
  --data-urlencode "from=2026-09-01T00:00:00.000Z"

# Unsubscribes per stated reason
curl -G "https://brew.new/api/v1/analytics/events" \
  -H "Authorization: Bearer $BREW_API_KEY" \
  --data-urlencode "groupBy=unsubscribeReason"

// Clicks per link on one send
const perLink = await brew.analytics.eventCounts({
  sendId: 'snd_8fK2mQ4p',
  eventType: 'clicked',
  groupBy: ['link'],
})

// Email events per type per day since September 1
const perDay = await brew.analytics.eventCounts({
  groupBy: ['eventType'],
  bucket: 'day',
  from: '2026-09-01T00:00:00.000Z',
})

// Unsubscribes per stated reason
const reasons = await brew.analytics.eventCounts({
  groupBy: ['unsubscribeReason'],
})

brew-cli analytics event-counts --send-id snd_8fK2mQ4p --event-type clicked --group-by link
brew-cli analytics event-counts --group-by eventType --bucket day --since 2026-09-01T00:00:00Z
brew-cli analytics event-counts --group-by unsubscribeReason

The answer is { count, groups, otherCount, range, truncated, coveredFrom? }:

groups holds the largest 200 groups, largest first. Each is { key, bucket?, count }: key maps each groupBy field to its value (null when the event has none), and bucket is the UTC period start.
otherCount sums the groups not listed.
One count reads the newest 20,000 events in the window. A busier window answers truncated: true, and coveredFrom marks where the counted events begin. Narrow from/to or add eventType to count all of it.

A count takes no cursor or automationRunId (400), and limit is ignored. It counts events, not unique recipients, and an unsubscribe counts once per reason it gave. For unique opened and clicked recipients, use GET /v1/analytics/overview. Over MCP, get_email_analytics with report.kind: "events" takes the same groupBy and bucket.

The Open-Time Profile

Brew keeps one open-time profile per contact: when in the day they open email. Ask a contact read for openProfile to get it. Intelligent send doesn’t read this profile. It times each contact from their human opens and clicks directly.

curl "https://brew.new/api/v1/contacts/jane%40example.com?include=openProfile" \
  -H "Authorization: Bearer $BREW_API_KEY"

const contact = await brew.contacts.get('jane@example.com', {
  include: 'openProfile',
})
const best = contact.openProfile?.bestSendMinuteUtc
if (best !== undefined) {
  const hh = String(Math.floor(best / 60)).padStart(2, '0')
  const mm = String(best % 60).padStart(2, '0')
  console.log(`Best send time: ${hh}:${mm} UTC`)
}

brew-cli contacts get jane@example.com --include openProfile --json

openProfile is null until Brew has recorded an open for the contact. Otherwise it holds:

Field	What it holds
`histogram`	48 open counts, one per UTC half hour of the day. Index 0 is 00:00 to 00:30 UTC, index 47 is 23:30 to 24:00. Each email counts once, at its first open.
`totalOpens`, `lastOpenedAt`	How many opens the histogram holds, and when the latest was.
`bestOpenMinuteUtc`	The minute of the UTC day (0 to 1439) the contact usually opens.
`bestSendMinuteUtc`	The minute of the UTC day to send, a few minutes before `bestOpenMinuteUtc`.
`confidence`	0 to 1: how much history there is and how tightly the opens cluster.

The last three appear only once there is enough history to name a best time. The profile counts opens as the mail provider reports them. Privacy proxies and security scanners that fetch images on delivery look like opens here, and nothing in the profile tells them apart, so don’t use it for bot detection. The event feed does classify each open: GET /v1/analytics/events leaves machine-classified opens out unless you pass includeMachineOpens=true.

For a Page of Contacts

POST /v1/contacts/search takes include: ["openProfile"] in its body and attaches the profile to each returned contact. Each row costs a profile read, so a page holds at most 10 contacts, whatever limit asks; pagination.limit reports the size read. count: true can’t be combined with it (400 INVALID_REQUEST). Over MCP, search_contacts takes the same include.

curl -X POST "https://brew.new/api/v1/contacts/search" \
  -H "Authorization: Bearer $BREW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audienceId": "jn7a8w4q8m9k2p1x7c3b5v6n9h7s2d4f", "include": ["openProfile"] }'

Either read needs the emails scope as well as contacts, because the profile is engagement data. A contacts-only key gets 403 INSUFFICIENT_PERMISSIONS when it asks for openProfile, and reads contacts without it as before.

GET /v1/analytics/events in the Public API v1 reference (sidebar): full schema + filters.
Reading analytics: the dashboard view of the same data.
Pagination: cursor semantics.

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.

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.

Start Here

Public API v1

API Contracts

API Guides

MCP Server

CLI

SDKs

Explore Per-Contact Engagement

One Contact’s Timeline

Export a Full Timeline

Filter by Event Type or Automation

Count Events Instead of Listing Them

The Open-Time Profile

For a Page of Contacts

Need Help?

Search Documentation

Ask ChatGPT or Claude

Schedule a Call

Call Us Directly

Slack Channel

Email Support

​One Contact’s Timeline

​Export a Full Timeline

​Filter by Event Type or Automation

​Count Events Instead of Listing Them

​The Open-Time Profile

​For a Page of Contacts

​Related

​Need Help?

Search Documentation

Ask ChatGPT or Claude

Schedule a Call

Call Us Directly

Slack Channel

Email Support

One Contact’s Timeline

Export a Full Timeline

Filter by Event Type or Automation

Count Events Instead of Listing Them

The Open-Time Profile

For a Page of Contacts

Related

Need Help?