Rheo documentation
User GuideEngage

Set up Engage

Connect email and push, point webhooks at your endpoint, manage consent, and keep email deliverability healthy.

Before you send

What you need depends on the channel:

ChannelBefore a live send
EmailA connected provider with a verified sending identity, a physical mailing address, and customers with an email address and granted marketing consent
WebhookAn https endpoint and a JSON object on the message. No provider connection
PushAt least one of APNs, Firebase Cloud Messaging, or Web Push saved here, plus a device the SDK has registered

Open App settings → Engage settings.

Email Settings (provider)

Rheo Engage supports one bring-your-own email provider per app:

  • Amazon SES
  • Resend
  • Postmark
  • SendGrid

Rheo orchestrates broadcasts and automations. You own the credentials, domain verification, and sender reputation.

Connect the provider

  1. Open App settings → Engage settings → Email Settings.
  2. Choose a provider and enter the shared from-address fields plus that provider's credentials.
  3. Set the physical mailing address recipients will see in compliance footers.
  4. Copy the shown webhook URL into your provider (or into SNS for Amazon SES) so bounce, complaint, and delivery events reach Rheo. This URL is for your email provider. It is not the Engage webhook channel.
  5. Refresh identity until status is verified. Do not send live email while identity is unverified.

Switching providers replaces the connection for that app after a successful save. You cannot keep two email providers active on the same app.

Set up Amazon SES

Engage sends through your Amazon SES account. Platform mail Rheo sends to workspace teammates (onboarding, billing, usage alerts) uses a separate Rheo-owned SES path. Do not point Engage SNS subscriptions at any Rheo platform webhook.

You need an AWS account that can send from SES, a verified domain (and from-address), and a workspace role that can manage Engage (owner or admin).

1. Verify your domain and from-address

  1. In AWS Console → SES → Verified identities, verify the domain you will send from.
  2. Publish the DNS records SES shows for DKIM. Also publish SPF and DMARC for that domain (Rheo does not crawl DNS; confirm them in your DNS provider).
  3. Use a from-address on that verified domain (or verify the mailbox explicitly in SES).
  4. If the AWS account is still in the SES sandbox, request production access, or only send to SES-verified recipient addresses while you test.

2. Create an SNS topic for delivery feedback

  1. In the same AWS region you will use for SES, create a Standard SNS topic.
  2. Copy the topic ARN (for example arn:aws:sns:us-east-1:123456789012:rheo-engage-ses). You will paste this ARN into Rheo so bounce, complaint, and delivery events are accepted only from that topic.

3. Create a SES configuration set

  1. In SES, create a configuration set (for example rheo-engage).
  2. Add an event destination that publishes at least bounce, complaint, and delivery events to the SNS topic from the previous step. See AWS SES event publishing.
  3. Note the configuration set name. Rheo attaches it to outbound sends so feedback events reach your topic.

Without a configuration set, Rheo can still send once identity is verified, but bounce and complaint suppressions and deliverability health will be incomplete.

4. Create IAM credentials

Create an IAM user (or access keys for a role your team manages) that can:

  • Send email with SES
  • Read email identity status (so Rheo can show verified / pending)

Create an access key ID and secret access key. Grant only the identities and actions you need.

5. Connect SES in Rheo

  1. Open App settings → Engage settings → Email Settings.
  2. Choose Amazon SES.
  3. Fill in:
FieldRequiredNotes
From emailYesMust match a SES-verified identity
From display nameOptionalShown as Name <email>
AWS regionYesMust match the region of your SES identity and SNS topic
Configuration setRecommendedName from step 3
SNS topic ARNYesExact ARN from step 2
Access key ID / Secret access keyYesFrom step 4
Physical mailing addressYes for complianceShown in email footers (CAN-SPAM)
  1. Save the connection. Rheo stores credentials encrypted, checks the from-identity against SES, and creates a per-app webhook URL.

6. Subscribe SNS to the Engage webhook URL

After save, Email Settings shows an Engage webhook URL for Amazon SES.

  1. Copy that URL.
  2. In SNS → your topic → Create subscription:
    • Protocol: HTTPS
    • Endpoint: the Engage webhook URL from Rheo
  3. Confirm the subscription shows as Confirmed in SNS. Rheo accepts the SNS confirmation automatically when the topic ARN matches what you saved.

Use only this Engage webhook URL. Do not reuse any other Rheo SNS endpoint meant for platform mail.

7. Refresh identity and review deliverability

  1. Click Refresh identity until status is verified. Do not launch live email while status is pending or failed.
  2. On the deliverability checklist, confirm DKIM/domain verification and that bounce and complaint notifications are wired through your configuration set and SNS topic.
  3. Publish SPF and DMARC if you have not already.

If hard bounce or complaint rates cross Rheo's hard thresholds, Email Settings shows Sending paused. Fix list quality or SES issues, then use Resume sending. That pause does not stop webhook or push.

8. Smoke-test before a real broadcast

  1. Use Engage test send, or a small broadcast to a consented contact on your test destination allowlist.
  2. Confirm the message arrives and that delivery feedback can reach Rheo through SNS.
  3. Then create a broadcast or automation.

Opens and clicks are tracked by Rheo. You only need SES (via SNS) for delivery, bounce, and complaint events.

Push settings

Open App settings → Engage settings → Push settings. Save only the platforms you send to. A push broadcast will not launch until at least one of these is connected.

PlatformWhat you save
iOS (APNs)Auth key (.p8), Key ID, Team ID, and the app bundle ID. Test-environment sends use the APNs sandbox
Android (FCM)A Firebase service account JSON for HTTP v1
Web PushA VAPID subject (mailto: or https://) and a generated keypair. The private key stays encrypted. Apps read only the public key

Devices register themselves from the SDK after notification permission. See the SDK overview.

Webhook messages

Webhook does not use Email Settings or Push settings. Each broadcast or automation step stores its own endpoint, headers, and JSON payload.

In production the endpoint must be https on a public host. Localhost, link-local, and private network addresses are rejected. In a message you can mark a header as secret. Rheo stores that value encrypted and always sends Content-Type: application/json, User-Agent: RheoEngage/1.0, and X-Rheo-Delivery-Id.

Open App settings → Engage settings → Marketing consent.

Grow+: Marketing topics mode is part of Advanced Engage. Indie workspaces cannot turn topics on.

  • Marketing topics mode is off by default. When you turn it on (Grow+), every broadcast and automation must pick a topic, and the preference center shows per-topic toggles.
  • Add topic keys and labels your team will recognize (for example product updates vs promotions).

Topic eligibility is stored on the customer's email record. With topics mode on, email, webhook, and push all require that address plus a granted topic.

Preference center

On the same Marketing consent page, the Preference center section lets you brand the hosted page where recipients manage consent. In the email composer, add Unsubscribe and Manage preferences links using the delivery merge tags {{unsubscribe_url}} and {{preferences_url}} (or equivalent links in your footer content block). Rheo resolves those tags per recipient at send time.

When topics mode is off, the preference center shows a single marketing opt-in toggle. When topics mode is on, recipients can manage each topic.

When someone shares an email inside your product, your engineering team should send that email and marketing consent through the SDK identify path so they land on the same Customer record. Do not rely on stuffing email into event traits for opt-in. Details live in the Developer Guide and Customer concept page.

Push registration is separate. A notifications grant in a flow calls registerPush() so Rheo can address that device. See Engage push.

CSV import

Customer or segment CSV imports that create email audiences require:

  • email
  • marketing_consent (granted or denied). email_marketing_consent is still accepted as a deprecated column. If both columns are present and differ, the row is rejected.

Optional columns include app_user_id and topic:<key> when topics mode is on. Imports without app_user_id create a Customer that can later merge when the SDK identifies the same email.

Re-grant after unsubscribe

On a Customer profile, granting marketing consent again after an unsubscribe requires an attestation note (how and when permission was obtained). Rheo stores that note with the consent change.

Frequency Cap, quiet hours, and test allowlist

Open App settings → Engage settings → Frequency Cap.

SettingWhat it does
Max emails per contact / Rolling window (days)Caps how many Engage email messages one person can receive in the window. Webhook and push are not counted
App default timezoneUsed when a Customer has no timezone, and for absolute broadcast schedules
Quiet hours (defer delivery)Grow+ (Advanced Engage). Defers email, webhook, and push to the end of the local quiet window instead of dropping them
Test destination allowlistLimits who may receive test-environment email. Webhook and push are not filtered by this list

Automations can optionally be marked Exempt from app frequency cap in their settings when a transactional-style email journey must ignore the cap.

Deliverability health

Email Settings shows deliverability health for your email connection. Rheo tracks email opens and clicks. Bounce and complaint events from your provider webhook update suppressions on Customers.

If hard bounce or complaint rates cross the hard threshold, Rheo shows Sending paused for email. Fix the underlying issue, then use Resume sending when you are ready. That pause does not stop webhook or push.

From the terminal

Email provider connect, push credentials, settings, health, and resume sending are available in the CLI with rheo engage provider, rheo engage push-provider, rheo engage settings, rheo engage health, and rheo engage deliverability resume. Connecting a provider and resuming sends require an owner or admin key.