Troubleshooting

This page is the first stop for diagnosing issues with Engage. Most problems fit into one of these categories.

Sends Won't Go Out

Campaign is stuck in queued status

Symptoms: clicked Send, status moved from draft to queued, then nothing.

Diagnosis path:

1. Open Diagnostics. Look at engage-dispatch cron status.
2. If the last run is more than 5 minutes ago, the cron is paused or failing. Contact support.
3. If the cron is fine, check the campaign's audience segment count. If the segment compiles to zero rows, no sends ever get queued.
4. Check whether all recipients are suppressed. The audience count may be high while the deliverable count is zero.

Dry run shows zero sends

Almost always a consent or suppression issue.

• Does your segment include marketing_email_consent = true (or sms/push variant)?
• Are you targeting an audience that already unsubscribed en masse?
• Check Settings > Suppression List for an unexpectedly large list.

Campaign was sent but no recipients got it

Check the campaign analytics page. The funnel will show one of:

• Suppressed > 0 - they were on the suppression list before send.
• Bounced > 0 - provider rejected. Check the bounce reason.
• Delivered = 0 with no bounces - provider may be paused. Check Diagnostics > Provider Status.

Journey Issues

Journey is published but no runs are starting

The entry trigger isn't matching. Check:

• The trigger filter expression - is it too restrictive?
• The re-entry rule - if never and the rider has been in this journey before, they cannot re-enter.
• The trigger event itself - is engage-event-ingest actually firing for the underlying event?

Manual test: create a journey with entry customer.created and no filter, then sign up a test customer. A run should appear within 5 minutes.

Run stuck at a wait node

Look at next_step_due_at on the run row:

• If it's in the past, engage-journey cron is stalled.
• If it's in the future, the wait is still in effect. Look at the wait duration on the journey definition.
• If the wait is until_event and the event never fires, the run will sit forever. Add a fallback duration as a safety net.

Same template fired twice for the same rider

Two possibilities:

1. Re-entry rule mismatch. If every_trigger re-entry is set and the trigger fires twice within a day, the journey enters twice. Switch to after_cooldown with N days.
2. 24-hour dedup window expired. If the rider got the template more than 24 hours ago, a second send is permitted by design.

Branch evaluated wrong path

Branches use the same attribute surface as segments. Check:

• The predicate syntax matches a real field name (rides.total_count not rides.totalCount).
• The operator is correct (gte vs gt).
• The value type matches (5 for numbers, not "5").

You can dry-run a single branch by hitting the journey's /preview endpoint with a sample customer ID.

Deliverability Problems

Emails landing in spam

Most common causes, in order:

1. DKIM/SPF/DMARC misconfigured on a custom sender domain. Run the wizard's Verify DNS again.
2. DMARC policy is p=none. Mail servers treat none as "no enforcement" and many bin you regardless. Move to p=quarantine minimum.
3. High complaint rate in the past 30 days has tanked sender reputation. Pause sends, investigate suppression rate, resume in a week.
4. Subject line or body looks like spam (all caps, lots of exclamation, money symbols, "FREE" everywhere).
5. List quality issue - if you're sending to a segment that includes many never-opened addresses, mail servers see that pattern and bin future sends.

See Sender Domain Setup for DKIM/DMARC, and Suppression List for list hygiene.

High bounce rate

Spike of >2% means dirty data:

• Recent imports without verification?
• Old segment that hasn't been cleaned in a year?
• Test data leaking into prod?

Investigate, clean, and only resume sending when bounce rate drops below 1%.

Spam complaints over 0.1%

Engage auto-pauses your subaccount's Postmark stream at 0.3%. Below that, you'll get an alert. Address the root cause before resuming:

• Is the audience really opted in?
• Is the cadence too high?
• Is the content recognizable as coming from you?

Variable Substitution

Variables show as {{customer.first_name}} literally in the sent message

The template payload doesn't have the variable wrapper. Re-open the template, confirm the double-braces, save, and re-dry-run.

Variable resolves to blank or null

The underlying field is null for that customer. Always use the default filter:

{{customer.first_name | default:"there"}}

{{ride.last_at}} shows a timestamp instead of a date

You need a date filter:

{{ride.last_at | date:"MMM D"}}

Supported formats follow standard date-fns tokens.

{{wallet.balance}} shows a number, not a currency

Use the currency filter:

{{wallet.balance | currency}}

Webhook Issues

Analytics frozen, delivered count stuck at zero

The provider webhook ingest is backed up. Check Diagnostics > Webhook Lag. Normal is < 10 seconds; if it's minutes or hours, the receiver is failing.

Postmark webhooks not firing

In Postmark, the webhook URL must match https://[your-domain]/api/engage/webhooks/postmark and the events Delivery, Bounce, SpamComplaint, Open, Click, and SubscriptionChange must all be checked.

Telnyx STOP keyword not being honored

The Telnyx webhook URL must be set to https://[your-domain]/api/engage/webhooks/telnyx, and the messaging profile must include inbound message events. Without inbound events, STOP keywords vanish into the void.

Compliance Validations

"Cannot publish: template missing unsubscribe variable"

The template body doesn't include {{unsubscribe.url}}. Open the template, add it to the footer, save, and try again.

"Cannot publish: subaccount legal address missing"

Go to Settings > Business Details > Legal Address and fill it in. CAN-SPAM requires it on every marketing email.

"Cannot publish: SMS template missing STOP hint"

Pre-built SMS templates include "Reply STOP to unsubscribe" in the footer. Custom SMS templates must include similar wording.

Performance

Segment preview takes more than 10 seconds

Either the segment definition is genuinely complex (4 levels of nesting plus many rules) or one of the underlying rollup views is slow. Contact support with the segment ID and they can pull a query plan.

Send pipeline backed up by thousands of queued sends

Check the rate limit defaults in Settings > Rate Limits. Defaults are 1000 emails / 5 min, 100 SMS / min, 5000 push / min. For larger blasts, contact support to raise the limit temporarily.

Account / Provisioning

Engage tab not showing in sidebar

Engage is on Pro and Enterprise plans only. Check your plan in Settings > Billing. Contact support if you're on Pro and don't see the tab.

Templates > Levy Recommended tab is empty

The seed wasn't run. Click Seed Templates if you have super-admin permission, otherwise contact support.

Custom sender domain stuck in pending after a week

DNS isn't propagating. Use dig TXT on each record to confirm they're live. If the DNS is correct, the Postmark side may be stuck - contact support.

Logs and Diagnostics

For any issue not covered above:

1. Engage > Settings > Diagnostics shows live system health.
2. Engage > Analytics > Export Audit Log gives you the compliance event trail.
3. The browser dev tools console will show API errors on the dashboard side.

When contacting support, include:

• The campaign ID or journey ID
• A timestamp of when the issue happened
• A screenshot of the analytics funnel or the error message

---