> ## 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.

# PostHog

> Start Brew automations from your PostHog product events, sync identified people to contacts, and let Brew's AI read your product analytics.

Connect [PostHog](https://posthog.com) to Brew so the events your product
already captures start automations. Someone signs up, finishes onboarding or
goes quiet, and the right email goes out. Brew can also keep identified
PostHog people in your audience and answer questions about your product
analytics in chat.

> [!WARNING]
>
> Every marketing recipient must have opted in to hear from you. Importing or syncing contact data into Brew is not permission to email it. See [What You Can Send](https://docs.brew.new/get-started/what-you-can-send.md).

## How It Works

Connecting PostHog gives you up to three parts, and you choose which ones on
the way in:

* **Event triggers.** Any event your PostHog project captures, plus your
  PostHog Actions, can start an automation.
* **Sync people to contacts.** Identified PostHog people with an email address
  become Brew contacts, with the person properties and key events you pick.
  It needs Event triggers on.
* **Analytics context.** Brew's AI reads aggregate event counts and your saved
  insights. It never reads person-level rows.

Brew adds a webhook destination named **Brew** to your project's data
pipelines. PostHog always sends `$identify` through it, so Brew learns who
each person is, and person updates while contact sync is on. Any other event
goes through only once a published automation uses it. Saving a draft changes nothing in
PostHog.

Each delivery is signed, and Brew checks the signature before it acts.

## Setup

**1. Connect PostHog in Brew**

Open **Integrations**, click the **PostHog** card and choose **Connect
PostHog**. Pick what Brew can access. Set **Project region** to where
you sign in: **US** for us.posthog.com, **EU** for eu.posthog.com. Click
**Continue to PostHog**.

**2. Approve one project**

Sign in to PostHog and choose a single project. Brew connects to exactly
one project per brand, and a project can belong to only one Brew brand.
If you picked the wrong region, Brew finds the project in the other one.

**3. Identify people with their email**

Brew sends to the email address stored on the PostHog person, never to a
`distinct_id`. Call `identify` with an `email` person property in your
app, as in [PostHog's identify docs](https://posthog.com/docs/product-analytics/identify).
Anonymous events can't start an automation.

**4. Pick an event**

The PostHog page lists your project's events under **Custom**,
**Standard** and **Actions**, busiest first. Click **Use as trigger** on
the one you want. Brew refreshes the list daily, so an event you just
started capturing shows up after the next refresh.

## Trigger Events

Brew lists up to 2,000 of your project's events from the last 30 days and up
to 500 Actions. Besides your custom events, it offers three standard ones:

* `$identify` (Person identified)
* `survey sent` (Survey response sent)
* `$exception` (Exception captured)

High-volume events such as `$pageview`, `$autocapture` and `$pageleave` are
not offered.

To test an automation before you publish it, open the event and turn on
**Receive before publishing**. PostHog then sends that event to Brew right
away. A source can receive up to 100 events, and a brand can have up to 100
triggers.

### What an Event Carries

Each event gives your email four groups of fields:

| Group | What's in it | Merge tag example |
| - | - | - |
| `properties` | The event's own properties | `{{ properties.plan }}` |
| `person` | The person's properties, `distinct_id` and `person_id` | `{{ person.first_name }}` |
| `event` | The event's name, ID and time | `{{ event.name }}` |
| `context` | Page URL, referrer, UTM tags, device and location | `{{ context.utm.source }}` |

Property names become lowercase snake case, so `$current_url` reads as
`current_url` and `projectName` as `project_name`. An event's preview in the
trigger picker lists the exact merge tag for each one.

Give a fallback to anything a person might not have, such as
`{{ person.first_name | there }}`. See [Merge Tags](https://docs.brew.new/create-emails/merge-tags.md).

### The Email Address

Brew reads the recipient from the person property named `email`. If your
project stores it under another name, change it under **Email address** on
the PostHog page.

Saving re-imports your contacts by the new property, and
live events use it right away. An event whose person has no email address
doesn't start an automation.

## Sync People to Contacts

With this part on, Brew imports every identified PostHog person who has an
email address. It reads them all when you connect and again each day, and
refreshes key-event dates every hour.

* **Person properties:** pick up to 25. Each lands on the contact as
  `posthog_<property>`. Brew tags properties that look like personal data.
* **Key events:** pick up to 5, such as an activation or upgrade event. Each
  adds `posthog_<event>_first_at` and `posthog_<event>_last_at` to the
  contact, looking back up to two years.

Each contact also gets `posthog_person_id` and `posthog_created_at`, plus its
name from the `first_name` and `last_name` person properties. Between daily
reads, identify and `$set` events keep the picked properties current. Deleting a person in PostHog leaves the Brew contact in
place.

## Starter Automations

Under **Starter automations**, the PostHog page offers four ready-made drafts:

* **Welcome new signups**
* **Activation nudge**
* **Trial conversion**
* **Win back people who went quiet**

Brew looks for common event names such as `signed_up` and `trial_started`. A
starter that is missing its event says which one it needs. **Create
automation** opens chat with the draft, and nothing changes in PostHog until
you publish it.

## Ask About Your Product Analytics

With Analytics context on, ask Brew in chat questions such as "How many
people signed up last week?" or "What does our activation insight show?".
Brew writes every query itself from your question.

It reads your saved insights and event counts from up to the last 90 days.
Any count that covers fewer than 5 people is held back.

Brew runs at most 120 queries an hour against a PostHog project. Its own
background work, such as contact sync, stops at 90, so chat always keeps 30.

## Troubleshooting

The PostHog page shows the destination's health:

* **Sending to Brew is off in PostHog.** Someone turned off the Brew
  destination. Brew never turns it back on itself. Turn it on in PostHog,
  then click **Test connection**.
* **PostHog isn't sending events to Brew.** Brew couldn't set up sending and
  keeps retrying. If it stays, reconnect PostHog. If PostHog refused Brew's
  access, reconnecting restores events.
* **No events in 7 days.** Published automations are waiting. Click **Test
  connection** to check the destination delivers.
* **PostHog refused an update.** Events already set up still arrive.
  Reconnect PostHog to add new ones.

**Test connection** sends a test event through the destination and says
whether PostHog delivered it.

## Disconnect

Disconnecting PostHog in Brew deletes the destinations Brew created. If Brew
can't delete one, the page asks you to remove it under **Data pipelines** in
PostHog, then click **I deleted it**.

Contacts Brew already synced stay in your audience.

## From an Agent or Code

Over [MCP](https://docs.brew.new/api-reference/mcp/tools.md):

* `list_integration_events` lists your PostHog events.
* `describe_integration_event` shows the fields one carries.
* `ensure_integration_event_trigger` creates its trigger.
* `check_trigger` confirms an event has arrived.

Over the API, see
[Live Integration Events](https://docs.brew.new/create-emails/automation-triggers.md#live-integration-events).
Connecting PostHog is app-only.

## Requirements

* A project on PostHog Cloud, US or EU. Self-hosted PostHog can't connect.
* People identified with an email address in a person property.

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

> [tab] Self-Service Tools
>
> > [card] Search Documentation
> >
> > Type in the "Ask any question" search bar at the top left to instantly find relevant documentation pages.
>
> > [card] [Ask ChatGPT or Claude](#top)
> >
> > Click here to open the **Copy page** menu at the top of this page, then send the page to ChatGPT, Claude, or your editor.

> [tab] Talk to Our Team
>
> > [card] [Schedule a Call](https://cal.com/team/brewdotnew/brew-demo)
> >
> > Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.
>
> > [card] Call Us Directly
> >
> > Need immediate assistance? Reach us at **+1-(332)-203-2145** for urgent issues or time-sensitive questions.
>
> > [card] Slack Channel
> >
> > Our preferred support channel. You'll receive an invite after signup for direct founder support and fast responses.
>
> > [card] [Email Support](mailto:support@brew.new)
> >
> > Contact us at **[support@brew.new](mailto:support@brew.new)** for detailed inquiries or if you prefer not to use Slack.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.