Notification Platform

Ductor's notification platform is the send side of an in-product messaging system: you register the people who can be notified, group them, decide which channels each one accepts, bind every channel to a provider, wrap the render in an envelope, and then fire a single trigger that fans out across every channel the recipient allows. This page walks that path end to end.

The receive side — the in-app notification centre an end user opens to read what was sent — lives on its own page: Inbox.

The path

Read it left to right: a subscriber is who you can reach, a topic is a fan-out group of subscribers, preferences decide which channels fire, an integration binds each channel to a provider connection, a layout wraps the render, and the trigger dispatches and records one delivery per channel.

Subscribers

A subscriber is a first-class recipient. It is matched on (tenant, external_id) at upsert time — external_id is your own opaque user id, unique per tenant — so a create with an id you have seen before updates the existing row rather than duplicating it. A subscriber carries profile fields (first_name, last_name, email, phone, avatar, locale, timezone) and an arbitrary data JSON blob. Delete is a soft delete: active flips to false and the row's endpoints and subscriptions stay queryable for audit.

The subscriber service (/api/v2/notification/subscribers, scope notification:read / notification:write) owns three sub-resources — endpoints, subscriptions, and preferences — for a total of fourteen operations.

Channel endpoints

A channel endpoint is the address at which a subscriber receives one channel via one provider. Channels are email, sms, push, chat, and in_app. An endpoint carries a channel, a provider_key (e.g. fcm, sendgrid), an identity (the email string, device token, chat id …), an optional connection_id referencing a connector connection, a verified flag for double opt-in, and free-form metadata. Uniqueness is scoped to (tenant, channel, provider, identity); re-adding the same address just refreshes its last_used_at.

curl -X POST "$DUCTOR_API/api/v2/notification/subscribers/$SUB/endpoints" \
  -H "Authorization: Bearer $DUCTOR_TOKEN" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"channel":"push","provider_key":"fcm","identity":"<device-token>","verified":true}'

The five-layer preference resolver

Whether a channel actually fires for a given trigger is decided by a five-layer resolver. The layers are ordered weakest to strongest; a stronger layer overrides a weaker one for a channel unless a weaker layer set that channel read_only (a lock a stronger layer may not flip).

Each preference row carries an all default channel decision, per-channel overrides (enabled, read_only, and an optional CEL condition), an optional weekly quiet-hours schedule, a record-level read_only lock, and an optional record-level CEL condition. UpdateSubscriberPreferences edits only layers 3, 4, and 5 — layers 1 and 2 are author-owned and set elsewhere. Layer 3 needs no extra keying, layer 4 needs workflow_key, and layer 5 needs workflow_key + topic_key + context_keys.

Preview the effective decision

Use preferences:preview to explain what dispatch would do for one subscriber and workflow before sending. It runs resolver version preference-v2 and returns each channel's allowed decision, stable reason_code, winning_layer, and ordered per-layer trace. Optional user_id, topic_key, context_keys, and channels make the preview match the intended trigger.

payload_context is available for CEL evaluation, but it is transient: encoded input is limited to 64 KiB and is never persisted or echoed in the response.

curl -X POST "$DUCTOR_API/api/v2/notification/subscribers/$SUB/preferences:preview" \
  -H "Authorization: Bearer $DUCTOR_TOKEN" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_key": "lead.assigned",
    "channels": ["email", "push"],
    "payload_context": {"lead_tier": "enterprise"}
  }'

Topics

A topic is a named, tenant-scoped group of subscribers and the fan-out unit. When a trigger is admitted, Ductor records a membership cutoff and then expands the eligible members as of that cutoff with stable keyset pagination. Membership changes after admission do not change that broadcast. Topics are keyed by {key} (a lower-snake-or-dot slug, 1–128 chars, unique per tenant); the key is immutable once created. Membership entries may carry context_keys that scope layer-5 preference resolution. Eight operations, on /api/v2/notification/topics, scope notification:read / notification:write.

Topic triggers are asynchronous and require the durable fan-out queue. There is no synchronous fallback: admission fails before acceptance if the payload object, manifest, or queue cannot be persisted. See Delivery Reliability for limits and recovery behavior.

Integrations

A notification integration binds a (channel, provider) pair to a connector connection that holds the encrypted credentials — it is the join between "I want to send email" and "here is the account that sends it". Five operations, on /api/v2/notification/integrations, scope notification:read / notification:write.

An integration carries a channel, a name (unique per (tenant, channel)), a provider_key, the connection_id, a priority (lower wins; defaults to 100, ties break by created_at ascending), an active flag, an optional CEL condition for conditional routing, an optional casing_override, and metadata. At dispatch time the resolver picks the highest-precedence active integration whose condition matches.

Layouts

A layout is a channel-scoped envelope template that wraps a content render through the {{ content }} placeholder — the outer shell (header, footer, styling) that every message on a channel shares. Layouts render with handlebars or liquid, are partitioned by channel (email, sms, push, chat, inapp), and at most one layout per (tenant, channel) may be the default. Nine operations, on /api/v2/layouts, scope layout:read / layout:write.

The content body must contain {{ content }} — create and update reject a body without it. :setDefault demotes the previous default on the same channel in the same transaction, preserving the at-most-one-default invariant. :preview renders the body server-side against a sample payload (replacing {{ content }} with a deterministic stand-in) and reports resolved and unresolved variables, so authors see the real envelope without client-side substitution drift. :duplicate clones a layout with a fresh identifier, a " (copy)" name suffix, and never marked default.

Trigger and deliveries

The trigger is the single send entry point. TriggerNotification resolves the recipient, runs the five-layer resolver, selects an integration per channel, renders through the layout, dispatches via the provider, and records one delivery per (channel, endpoint). Five operations cover dispatch and recovery, scope notification:read / notification:write; redrive requires notification:admin.

The recipient is exactly one of: subscriber_external_id (with an optional inline subscriber profile that is upserted before dispatch), an existing subscriber_id, or a topic fan-out. You may restrict channels and pass per-channel overrides; an omitted channel list means every channel the preferences allow. The response echoes the transaction_id and a per-channel/endpoint outcomes list (sent / failed / skipped). For an accepted topic trigger, outcomes accrue asynchronously in delivery records rather than in the admission response.

ListNotificationDeliveries reads the recorded rows by exactly one of transaction_id (every channel/endpoint from one trigger) or subscriber_id (recent deliveries, newest first). Each row carries channel, status (queued / running / sent / failed / skipped), provider message id, typed failure phase and code, preference reason code and resolver version, retry timing, execution and provider attempt numbers, downstream observation state, reconciliation flag, and timestamps.

curl -X POST "$DUCTOR_API/api/v2/notifications/trigger" \
  -H "Authorization: Bearer $DUCTOR_TOKEN" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_key": "lead.assigned",
    "subscriber_external_id": "user_42",
    "payload": {"lead_name": "Acme Corp"}
  }'

The dispatch feature flag

The dispatch path is gated by the config flag notification.dispatch.enabled. The management surface — subscribers, topics, integrations, layouts, preferences — is always available; the flag gates only the send itself.

Where to go next