Skip to main content
Use this guide to create a custom event, build an event-triggered flow on it, and test the path before launch. For a concrete welcome sequence, follow the Build a Welcome Flow recipe. Prefer to watch first? The seven minute walkthrough covers the same ground. Each Watch this step link below opens it in a new tab at the matching moment.
Before you start. Add a brand and verify a sending domain. If your backend will fire a custom event, create an API key for the active brand. Watch this step (0:42)

​
Create a Custom Trigger Event

Create the event first, so the flow has a trigger to start from.
1

Create the event

Open Automations, click Triggers, then New custom trigger. Use a specific name such as user_signup, order_placed, or subscription_renewed.
2

Define the payload schema

Add each field the event will send and mark required fields, then click Create trigger. Include a required email field for routing:

​
Create the Flow

1

Describe the flow

Open Home and describe the trigger, emails, timing, and outcome. For example:
“Build a two-step onboarding flow for new trial users. Trigger it when user_signup fires. Send a welcome email, wait 3 days, then send a quick-start email.”
Watch this step (1:51)
2

Review the canvas

Brew opens the flow canvas with the trigger, Send Email nodes, and Wait nodes laid out from left to right. Click a node to open its configuration panel.Watch this step (4:50)
3

Use the event in the flow

Make sure the trigger node uses your event. To pick it, click the trigger node and use Change trigger. Brew adds the event’s schema to the trigger node, so email content can reference fields with {{ fieldName }}. See Merge Tags for the syntax and for what happens when a field is missing.Watch this step (2:41)
4

Edit the flow

Prompt changes in the flow chat, or edit a node directly. For example:
  • “Change the wait to 4 days”
  • “Add a branch after the second email for contacts who clicked”
  • “After the wait, skip contacts whose plan is now pro”
A condition after a Wait reads the contact as it is at that point. See Conditions After a Wait.New flows start as Draft, and each edit saves a new version. The flow stays in Draft until you publish it after the test passes.Watch this step (5:25)
Firing, running, and testing an automation cost no credits. Email sends inside the flow count toward your monthly send limit.

​
Test and Publish

1

Test before launch

Open the flow and click Test automation. Enter your address under Send test to, fill in the trigger payload under Test data, then click Run test.Brew runs the full flow and sends every email to the test address only. Real contacts in the payload are never reached, and test runs don’t affect analytics.
2

Publish and monitor

When the test looks right, click Publish in the canvas header to make the flow Live. The next matching event starts it automatically. Open the automation from the list to review execution history and failures.Watch this step (6:02)
3

Fire the event from your backend

Your backend sends the event to Brew with an API key for the active brand. Fire only after the flow is published, since an unpublished trigger refuses the fire.Each event carries a stable key, such as the user’s ID, so a retry doesn’t start the flow twice. The request is in From an Agent or Code.

​
Start a Flow When Someone Unsubscribes

Brew owns this trigger, so there is no event to create or fire. Unsubscribe Events is the reference for its scopes and payload.
1

Pick the trigger

In the trigger picker, choose When a contact unsubscribes. Then, under Which unsubscribes start it?, pick the list it watches: All emails or one marketing domain.
2

Write the email

The contact has just opted out. Send only what they need, such as a confirmation of the unsubscribe, from a transactional domain. Never send them a promotion.Give optional payload fields a fallback so the email reads well either way:
3

Test and publish

Test the automation. It runs on Brew’s sample unsubscribe, and any payload fields you pass replace the sample’s. Then publish it.

​
Send a Transactional Email

A transactional email is this same flow with its Send Email node on a transactional-purpose domain. Transactional Email owns the setup steps, and What to Know Before You Ship One covers suppression, codes, and tracking.

​
Keep Event Schemas Maintainable

Name events for the action they describe, such as user_signup, and avoid names like event1, trigger, or do_thing. Declare only the fields an email will use, since every field you declare is one more to maintain, and type every field. Custom Events is the reference for names, schema shapes, and nesting.
If a payload is missing a required field or uses the wrong type, Brew rejects it. The automation doesn’t start.See What Happens When a Payload Fails Validation. Fix the payload and send it again.

​
From an Agent or Code

Fire the event. POST /v1/automations/triggers/{triggerEventId}/fire with an API key for the active brand. Send the moment’s data as payload. The email reads it as {{ trigger.* }}, and the email field routes the run to a contact.
  • Idempotency. Send a stable Idempotency-Key per event, such as signup-<userId>, so a retry can’t start the flow twice. See Idempotency.
  • Unpublished trigger. A fire before any attached automation is published returns 422 NO_PUBLISHED_AUTOMATION.
  • Bad payload. A missing required field or a wrong type returns 400 INVALID_PAYLOAD.
  • Ready check. GET /v1/automations/triggers/{triggerEventId}/readiness runs the auth, scope, and permission gates without firing, then returns the payload contract and the automations a fire would match. Over MCP, check_trigger does the same, and adding payload validates an example against the contract.
  • SDK. brew.automations.triggers.fire({ triggerEventId, payload }).
  • Test and publish over MCP. test_automation with a testRecipient runs the flow end to end to one address, and save_automation with published: true sets it live.
  • MCP confirmations. On OAuth and organization connections, fire_trigger_event first returns a confirmation request. After you approve it, the agent repeats the call with confirmed: true and the returned confirmation_id. A fire to an unsubscribed address answers RECIPIENT_UNSUBSCRIBED.
See the API Reference for the full request contract.

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

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.