Skip to content

Concepts

The vocabulary used everywhere else in these docs.

Scope: organization and environment

Every object belongs to one organization and one environment (for example acme and production). Together they form a scope. An API key is bound to exactly one scope, and every query it makes is filtered to that scope. Two environments never see each other’s subscribers, workflows, integrations or messages, and a key from one cannot read the other.

notify bootstrap -org <name> -env <name> creates an organization, an environment and the first key. The console can add more environments (Settings, Environments).

API keys and sessions

There are four credentials. They are not interchangeable.

CredentialHeaderUsed for
API keyAuthorization: ApiKey <key>All /v1 routes. A backend credential: keep it off devices.
Subscriber sessionAuthorization: Bearer <token>Only the inbox message routes, and only for one subscriber. Minted by your backend. See Subscriber sessions.
Source keyAuthorization: SourceKey <key>Only POST /v1/sources/{sourceID}/events. See Streams and webhooks.
Inbound secretX-Inbound-Secret: <secret>Only POST /v1/inbound/email. See Inbound email.

API keys are stored as a hash and shown once, at creation. notify rotate-key replaces the key for a scope and revokes every existing key for it.

Subscribers

A subscriber is a recipient. You identify them with your own subscriberId string (a user id, for example), and optionally give an email address, phone number, first and last name, locale, timezone and a free-form data object. Templates read these as {{subscriber.email}}, {{subscriber.firstName}} and so on.

You can create subscribers explicitly with POST /v1/subscribers, or implicitly: the to object of a trigger creates or updates its subscriber.

A subscriber also has channel addresses for providers that need one (an ntfy topic, a Telegram chat id, a browser’s Web Push subscription) and preferences (which channels they accept, per workflow, and their digest cadence). See Channels.

Topics

A topic is a named group of subscribers with a key. Triggering a workflow to.topicKey fans out to every member, one run each, under one transaction id.

Workflows

A workflow is a triggerIdentifier (a lowercase slug such as order-shipped) plus an ordered list of steps. Triggering the identifier runs the steps in order for a recipient. A workflow can be inactive (triggers are refused), and can be marked critical, which means subscribers cannot opt out of it. See Workflows.

Integrations

An integration is a stored provider configuration for a channel: an SMTP account, a Resend API key, an ntfy server, a Telegram bot, a Twilio account, and so on. Credentials are encrypted at rest with the master key and never returned by the API (secret fields come back masked). A channel can have several integrations; the one marked primary is used unless a step names another by identifier. See Channels.

Runs, notifications and messages

Triggering a workflow produces three kinds of record:

  • A run on the dagnats engine: the durable execution of the workflow’s steps for one recipient. Runs survive restarts.
  • A notification: one row per trigger per recipient, tying the transaction id, subscriber, workflow and run together. GET /v1/notifications.
  • Messages: one row per delivery attempt that a channel step records, with channel, provider, status (sent, error, skipped or throttled), the rendered subject and content, and the seen, read and archived flags. The in-app inbox is the list of in_app messages. GET /v1/messages, GET /v1/notifications/{id}/messages.

A transaction id names one logical send. If you supply it on a trigger, repeating the call with the same id and recipient does not start a second run.

Agents and conversations

An agent is a conversational endpoint registered in a scope. A conversation is a thread between an agent and a subscriber, with an append-only transcript. Messages posted to an agent start a turn that runs durably on the engine, using the agent’s runtime: mesh (dispatched over NATS to an external agent). See Inbox and agents.

Supporting objects

ObjectPurpose
LayoutsHTML wrappers for email bodies, with the rendered body injected as {{content}}.
TranslationsPer-locale key/value maps; templates call {{t "key"}}.
ContextsTyped records keyed by type and id, with JSON data, managed through /v1/contexts.
Environment variablesPer-environment key/value pairs, optionally secret (encrypted). Managed through /v1/env-vars.
Outbound webhooksURLs that receive delivery-status events and email replies, signed with HMAC.
Inbound domainsDomains you receive reply mail on.
Stream sourcesCredentialed producers that push events into the environment’s feed.

How a trigger runs

  1. The API authenticates the key and resolves the scope.
  2. The trigger service finds the workflow by name, refuses if it is missing, inactive or empty, and upserts the recipient.
  3. It starts a run on the dagnats engine, with an idempotency key built from the transaction id and the subscriber.
  4. The engine dispatches each step as a task. notify claims it over NATS with dagnats’ worker SDK, runs the step (render, check preferences, send, record a message) and reports back.
  5. Regular delays and digests are engine-native sleeps, and so are scheduled and dynamic delays where the engine can express them (see Delay). Those hold no notify worker while waiting and a restart loses nothing. The remaining waits run as long-lived tasks that recompute their remaining time after a restart.
  6. Delivery-status events go on a JetStream stream, which feeds analytics, the console’s live activity view, and your outbound webhooks.