> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedreach.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Planning Engage Automations
> A planning guide for partners adopting Engage: how automations and segments work, how to translate business goals into supported triggers, and what data you need to send us.
Read this *before* you start scoping the data integration — it will save you a redesign later. Planning for Reputation builds on the same concepts; see the [Planning Reputation Automations](/onboarding/planning/reputation) guide once you've worked through this one.
## The mental model: automation → segment → customer
Three concepts, in this order:
1. **A customer** is one person at one of your tenants. They have an identity (email and/or phone), some attributes (name, opt-in status, custom fields you define), and a history (transactions, events) that you've sent us.
2. **A segment** is a saved question about customers: *"which of this business's customers match these conditions right now?"* Segments are always lists of *people*, never lists of things or events.
3. **An automation** is a trigger plus a sequence of actions. When the trigger fires for a customer, that customer is run through the action sequence — typically an email or SMS, optionally with waits and follow-ups in between.
Every automation answers two questions: **when does it fire?** (the trigger) and **who does it fire for?** (the audience, which is one or more segments). Phrasing both in terms a Reach segment can express is the key to building the automation you want — the [customer-centric rule](#the-customer-centric-rule-and-how-to-reframe-a-business-event) below shows how to get there.
## The three trigger types (and only three)
Every automation on Reach uses exactly one of these. There are no others.
| Trigger | What it does | Typical use |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Broadcast** *(one-time)* | The automation runs once, at a scheduled timestamp (or immediately). Everyone in the audience receives the action sequence on that one run. Then the automation is done. Think of this as a single send to a list, not a recurring rule. | A holiday promotion. A one-off announcement. A campaign to win back lapsed customers in Q4. |
| **Segment entry** *(trigger-based)* | The automation runs for a customer the moment they *enter* a chosen segment. Nearly anything can be modeled as "customer entered segment X," which makes this the most flexible trigger in the system and the one most automations are built on. | A welcome series when a customer is first added. A reminder when a customer becomes overdue. A win-back when a customer hasn't purchased in 60 days. |
| **Date-based** | The automation runs once a year, on a fixed calendar date (e.g. March 15). On that date, everyone in the audience runs through the action sequence. | An annual greeting on a specific holiday. A yearly client appreciation message tied to a known calendar date. |
**Important nuance on date-based triggers.** "Date-based" means a *fixed* month and day for the whole audience. It does **not** mean "send 30 days before each customer's renewal." Per-customer relative dates (birthdays, anniversaries, days-since-purchase, days-until-X) are handled by *segments*, not by date-based triggers. You build a segment like "renewal date is between 30 and 31 days from today" and pair it with a segment-entry trigger.
**Timezone.** All waits and date-based triggers currently evaluate in `America/New_York` (EST/EDT). Plan messaging windows accordingly.
## What a segment can ask about a customer
A segment is a set of conditions joined by AND/OR. Each condition asks about one of the following:
### Built-in customer fields
* `email`, `phone`, `firstName`, `lastName`, `userId`
* Opt-in / opt-out status for email and SMS
* HIPAA consent (if applicable to your vertical)
### Custom fields you define
When you set up your integration, you describe a schema for the customer attributes your platform tracks. Anything in that schema becomes a segmentable field. Examples: `loyalty_tier`, `preferred_location_id`, `plan_type`, `signup_source`.
### Transaction or event history
You can also send us per-customer records — appointments, invoices, orders, reservations, claims, whatever your domain uses. Segments can then ask count-based questions ("has at least 2 invoices in the last 90 days") or date-based questions ("most recent appointment date is within the last 30 days").
### Operators available
Standard comparison (`equals`, `not equals`, `greater than`, `less than`, `contains`, `in [list]`, `exists`, `not exists`) plus date-specific operators that make the customer-centric reframe possible:
* **Today-relative dates:** "field is within last N days," "field is N days from today (before or after)." This is how you express "30 days before renewal" or "7 days after signup."
* **Month/day matching:** recurring annual conditions like "birthday is today" or "anniversary falls in March."
* **Related-resource counts:** "has at least N *X*" where X is a transaction or event you've sent us.
If you can phrase your audience as *"a customer who satisfies these conditions right now,"* you can build it as a segment. If you can't, see the next section.
## The customer-centric rule, and how to reframe a business event
**The rule:** a Reach segment returns *customers*. The question being asked can be about a customer's own attributes *or* about the records related to them — bookings, invoices, appointments, sessions — but the answer is always a list of people. There is no "60 days before a tournament starts" trigger, because a tournament on its own is not a customer.
This shift in framing is the most valuable move you can make during planning. Partners whose product is built around scheduled events, appointments, renewals, or expirations naturally think in business-level events — and the good news is that almost any business-level event you care about can be expressed as a question about customers. The most common technique is to reach *through* a relationship the customer has to another record, and once you've done that translation, the rest of the automation falls into place.
### Working example: a pet-boarding platform
Suppose your platform serves kennels and pet boarding facilities. Each tenant has customers who book multi-day stays. Your tenants tell you: *"I want to send a reminder 7 days before each customer's stay begins, asking them to confirm and complete pre-check-in forms."*
The instinct is to phrase the trigger as a business event: *"7 days before a stay starts."* But "a stay" on its own is not a customer — it's a record that *belongs* to one. The fix is to phrase the question about the customer's relationship to that record.
Decide which records on your side belong to a customer and matter for messaging. For this partner: each customer has zero or more *bookings*, and each booking has a `start_date`, an `end_date`, a `status`, and so on. Send those bookings to Reach as related records attached to the customer.
"Customers who have at least one booking whose `start_date` is between 7 and 8 days from today and whose `status` is *confirmed*." The segment still returns a list of people — but the condition reaches into each person's bookings to find the match.
When a customer enters the segment — that is, when one of their bookings crosses the 7-day threshold — the automation fires and the reminder goes out. As bookings get added, edited, or cancelled and resynced, customers naturally move in and out of the segment.
This pattern generalises. "Send a follow-up to customers whose most recent invoice was paid more than 30 days ago" → segment on *"has at least one invoice with paid\_date more than 30 days ago, and zero invoices with paid\_date in the last 30 days."* "Win back customers who haven't visited in 90 days" → segment on *"has at least one visit, and zero visits in the last 90 days."* The shape is the same: ask about the customer's related records, count or date-filter them, return the customers who qualify.
When the relationship doesn't add anything — for example, the data you care about really is just a property of the customer, like `loyalty_tier` or `signup_date` — you can also segment directly on a customer attribute. Both work. Choose the model that matches how your platform actually stores the data.
**Heuristic:** if the event you care about belongs to a customer (a stay, an invoice, an appointment, a renewal, a session), you can almost always express it as either a customer attribute or a question about related records. If the event truly belongs to the *business* and not to any specific customer (e.g. "the store's 5-year anniversary"), you can't trigger from it — but a broadcast or date-based automation may cover the use case.
## A working example, end to end: a pool-cleaning winback
To make all of this concrete, here's an Engage automation built the way a partner serving pool-cleaning businesses might design it. It uses the related-records pattern above and shows what the final automation looks like in the builder.
### The automation
**Goal.** Win back customers who used to book regular pool cleanings but have lapsed. The thinking: if a customer hasn't had a cleaning in the last 30 days and doesn't have one on the books, they're at risk of churning. Send them a friendly nudge. If they still haven't booked 15 days later, follow up once more.
**How it works.** A segment finds qualifying customers. The moment a customer enters that segment, the automation sends the first email. It then waits 15 days. Before sending the follow-up, it checks whether the customer is *still* in the segment — if they booked a cleaning during the wait, they've already fallen out and the automation exits without bothering them. If they're still lapsed, it waits until the next 9 AM and sends the second email.
### The segment
Each customer at a pool-cleaning business has a collection of *cleanings* sent to Reach as related records. Each cleaning has a `service_date` (when it happened, or is scheduled for) and a `status` (`completed`, `scheduled`, `cancelled`). The segment asks three questions about that collection:
| Condition | What it checks |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Has at least 1 cleaning where `status = completed` | The customer has been a customer at some point — we don't want to nudge brand-new contacts who never booked anything. |
| Has 0 cleanings where `status = completed` AND `service_date` is within the last 30 days | They haven't been serviced recently. |
| Has 0 cleanings where `status = scheduled` AND `service_date` is in the future | And they don't have anything on the books either. |
Joined with AND, this returns: *"customers who have used us before, haven't been serviced in the last 30 days, and have nothing scheduled."* Exactly the at-risk cohort.
The segment is dynamic. As days pass, customers cross the 30-day threshold and enter the segment. As customers book a new cleaning, they exit. The automation reacts to both transitions automatically.
### The flow
This is what the automation looks like in the partner-dashboard builder:
Two steps make this flow smarter than a simple two-message sequence. The **check segment membership** step keeps the messaging relevant — it reevaluates segment membership at that point, so a customer who booked a cleaning during the 15-day wait exits the automation cleanly and never receives a redundant nudge. The **wait until 9 AM** step makes sure the follow-up lands at a friendly time of day, 9 AM on day 15 (or the next morning if 9 AM has already passed), rather than whatever hour the previous wait happened to end on.
To run this automation, the partner needs to send Reach: each customer's cleanings (as a collection of related records, each with `service_date` and `status`), and a stable customer identity (external ID, email, name). That's it. Everything else — the segment, the trigger, the timing, the messages — is configured inside Reach.
## What you must send us
Before any of the planning in this guide can run in production, your platform has to deliver the underlying data. Roughly:
### Customer identity
* A stable **external ID** per customer (your platform's identifier).
* **Email** (required to send email), **phone** (required to send SMS), or both.
* **First and/or last name** (for personalization and compliance footer requirements).
* **Opt-in / opt-out signals** for email and SMS — either as fields, or via the events when consent changes.
### Business locations
Every tenant has one or more **business locations**, and every location is mapped to a Google Business Profile (GBP). This mapping is what allows Reach to direct review requests to the right GBP and attribute the resulting reviews back to the correct location. It matters most for multi-location tenants — where one tenant might have a dozen GBPs to route reviews to — but every tenant needs at least one location record for review attribution to work.
If a customer interacted with a specific location and you want messaging to be scoped accordingly (only customers at the Brooklyn branch, only customers whose preferred location is closed for the season), the customer's preferred or assigned location is a relationship field on the customer — see [Custom attributes](#custom-attributes-on-the-customer) below.
See [Location Data](/data-sharing/requirements#location-data) in the data-sharing requirements for the full list of fields.
### Custom attributes on the customer
Anything you want to segment on that lives directly on the customer. You'll declare these in a schema mapping during onboarding. Examples:
* Customer lifecycle fields: tier, plan, status, signup source.
* Relationship fields: assigned staff member, preferred location, account owner.
* Roll-up date fields, if it's easier to compute them on your side than to send the underlying records: `last_visit_date`, `next_appointment_date`, `renewal_date`.
### Related records (the bookings model from the reframe section)
If your tenants' work is naturally a stream of records per customer — bookings, visits, orders, invoices, claims, sessions, reservations — send those records as related collections rather than flattening them onto the customer. Segments can then count them, find the most recent, filter by date window, or check status. This is almost always the more powerful model: you avoid having to precompute and resync derived fields, and you can express richer questions ("has at least one upcoming booking *and* at least one completed booking in the last year").
### Keep it fresh
Whatever you send must be kept up to date. A segment that asks about a customer's upcoming bookings only works if those bookings are resynced to us when they're added, edited, or cancelled. Automations are only as good as the data behind them.
## Messages, copy, and the email template
An automation isn't just a trigger and an audience — it's also what gets sent. The work to produce that content runs alongside the planning in this guide, not after it. Two parts:
### The email template (one per partner)
As part of onboarding, you'll work directly with Reach to craft a default **email template** — the layout, branding, header/footer, typography, and link styling that wraps every email your tenants send through the platform. You only do this once, and it serves as the starting point for every message in every automation, across every tenant.
Per-tenant branding is automatic. Each tenant's logo, accent colour, business name, address, and other business details are injected into the template via merge fields, so an email from one tenant looks like it came from them and an email from another tenant looks like it came from them — without you or the tenant having to do anything.
From there, two layers of explicit customization exist:
**At the partner level (you).** You can tailor the default template at any granularity you need:
* Override the template for a specific automation (e.g. a distinct look for win-back campaigns).
* Override it for a specific message inside an automation (e.g. a different banner image on just the follow-up).
**At the tenant level (your customers).** Each tenant inherits your defaults — including any partner-level overrides — and can customize further within their own account:
* Override the template for a specific automation or message in their account.
* Bring their own template entirely if they have brand or design requirements your default doesn't accommodate.
Tenant customizations stay scoped to that tenant; they never affect your defaults or other tenants.
Start thinking about the default template early. The decisions are concrete and small in number, but they set the visual identity of every email and you don't want them blocking your launch.
### Message copy (one per automation)
For every automation in your inventory, someone has to write the actual subject line, email body, and — if SMS — the SMS text.
Two practical notes:
* **Draft copy as you plan each automation.** You don't need final wording — even a rough first draft makes the audience and trigger decisions much more concrete, and surfaces things like "this only makes sense if we know the customer's first name" that affect the data side.
* **Personalisation tokens.** If a message needs to address the customer by name, mention their next appointment date, or reference any other piece of customer data, that data needs to be syncing to us. Note the personalisation requirements when you draft the copy so they roll up into your data requirements alongside segment fields.
## Capturing your plan
The intended outcome of working through this guide is a concrete plan with three parts:
1. **An automation inventory** — every Engage automation you want to pre-populate for your tenants. For each, the business goal, the trigger type, the channel, and a draft of the message copy.
2. **An audience translation** — for each automation, the segment definition in terms of fields and operators (or questions about related records), plus a marker of whether it's buildable today, buildable once you send additional data, or something you want to walk through with Reach.
3. **A data checklist** — every field referenced across your segments, rolled up into a single list with current sync status. This is what your engineering team scopes against.
During onboarding, Reach will provide a worksheet that organizes these three pieces into a single document. You'll fill it in, send it back, and we'll review it with you — flagging anything that doesn't fit the supported model and confirming the data fields against our schema-mapping format before your engineers start integrating.
Questions, edge cases, or a use case you can't fit into the model? Bring it to your Reach contact early — most apparent blockers turn out to be reframings, and the few that don't are worth knowing about before you ship.