Lifecycle journeys

Use Communications → Journeys to send one reviewed email or in-app message after a person performs a tracked action. Journeys require Analytics, People and Communications in the application. Select the environment before creating the workflow.

Set up a journey

1. Define and activate the custom trigger event in Events → Tracking catalog. If the journey checks a later action, define that event too. Required properties and types are checked against the frozen catalog revisions.
2. Create a draft with a trigger, an elapsed delay of 1 minute to 7 days, a condition, and one message template. Optionally restrict eligibility to a current static or property-based People segment. Event-dependent segment definitions are refused; use the catalog-event condition for behavior.
3. Check the frozen preview. It renders the same sanitized Markdown and reviewed links used for delivery. An optional person ID checks an existing waiting or queued run; preview never enrolls, advances or sends.
4. Request approval. A different operator with Communications approval, Analytics read and People PII read reviews the exact revision and fingerprint. Neither its author nor its submitter can approve it. An unused approval expires after seven days and can be submitted again.
5. Activate future entries. Saving, requesting approval and approving do not activate the journey. Send a new identified custom track event through the existing browser, Node or Python SDK after activation.

Authors need Communications write, Analytics read and People PII read. Every change requires a passkey verified within ten minutes, same-origin CSRF protection, current organization access and an audit reason. Summaries require Communications read; private definitions and personal run history also require People PII read.

// Use the existing configured, consented SDK client after identifying the person.
saaspro.track('Trial Started', { plan: 'team' });

The event must conform to its approved tracking plan. It needs a persistent identified identity, a timestamp after activation and arrival within 24 hours. Ephemeral, anonymous, historical and invalid-plan events do not enroll. Events are observations from the application; a browser identity is not independent proof of account ownership. Use your authenticated backend for security-sensitive business events.

Conditions and suppression

The worker waits elapsed minutes from receipt, then either sends the approved message or exits. An observed-event condition checks retained, schema-valid events in the same environment since entry. “No event observed” describes available evidence, not proof that a person did nothing: it requires unchanged 100% Analytics sampling and no recorded sampling, budget, cardinality or disabled-signal losses over the window. Known incomplete or malformed evidence suppresses the run. Upstream delivery gaps cannot be measured by the control plane.

People segments use current application-wide membership or properties. Their definition is frozen in the approval, while membership can change during the delay. Editing a catalog or segment definition invalidates the approved reference and suppresses delivery until a new journey revision is reviewed.

At enrollment and again before dispatch, the system checks current modules and operator permissions. Before dispatch it also checks the identified person, retained source event, current condition, email opt-out and earlier bounce, frozen template and links, exact recipient, and frequency allowance. A missing or unknown required check suppresses delivery. Email journeys always use marketing unsubscribe rules.

Delivery and history

Each journey admits a person at most once during its configured 1–30-day cooldown, with one active run per person. All journeys together reserve at most one dispatch per person and environment in 24 hours. These allowances remain consumed when a provider receipt is unknown.

The worker stores the approved revision on each run and creates one campaign and one delivery atomically. Duplicate events and job retries reuse durable state. Email uses the configured platform provider; in-app uses the application's signed connector. A provider acceptance is not final delivery. In-app acceptance requires an exact queue receipt. Local email logging has no provider receipt and appears as unknown.

A timeout, lost response or interrupted dispatch is unknown, with automatic retry stopped. Check the provider before taking any separate action. Existing campaign retry controls cannot restart a terminal journey run. An operator can cancel a waiting or queued run, pause future enrollment and cancel pending runs, or archive the journey. A message already in flight cannot be retracted.

Editing creates a new draft revision, cancels pending runs and clears approval. Resuming a paused approved revision starts future events; it does not backfill or restart canceled runs. Identity merges preserve cooldown and opt-out state and cancel losing pending runs. Deleting a person removes their journey state and prevents pending delivery; dispatch already in flight has the same irreversible boundary.

Bounds and operation

Each environment supports 20 journey definitions, 100 revisions per journey, 2,000 entries per UTC day, 20,000 retained runs and 20,000 person-state rows. The complete frozen definition is limited to 24 KiB with at most 50 links. Per-journey daily caps can be smaller. Capacity refusals are visible and are not backfilled when capacity returns.

The durable communications.journeys.maintain job checks up to 50 scopes and 100 due runs per scope every minute. It persists attempt order before processing and continues after an individual scope failure. A run expires 24 hours after its due time. Queries immediately apply the smaller of application retention and 30 days; the worker purges run-owned campaigns, deliveries and People activity receipts in bounded batches, including orphan campaigns. A provider receipt that arrives after run retention or person deletion cannot recreate an activity row. Cooldown state is retained for 31 days after activity to preserve the maximum cooldown. Application, environment and person deletion cascade their relevant state. Definition revisions remain until the application/environment is removed, within the fixed definition and revision limits.

The read-only Management endpoint is GET /api/v1/apps/{app}/communications/journeys?env=production; add journey={id}&offset=0 for a 25-run private detail page. It uses Management tokens and current scoped permissions. Ingest keys cannot read journeys or approve/activate them.

This version supports one trigger, delay, condition and approved message per workflow. It does not include arbitrary code, multi-message branches, personalization, transactional-mail bypasses or Slack broadcasts.