How it works

What happens between your call and the delivery: the five things notifkit stores, and the five services a request passes through.

The five nouns

Everything in notifkit is one of these, and every endpoint is CRUD on one of them, plus notify(). Learn these and you know the API.

User

A person, keyed by your identifier, plus the rules for reaching them: accepted channels, accepted topics, and quiet hours. Because these live centrally, you call notify() without writing a preference check first.

Contact

One address on one channel: an email address, phone number, push token or webhook URL. A user has many. email: ["[email protected]", "[email protected]"] creates two contacts, and an email send fans out to both. A push token the provider reports as invalid is deactivated automatically, so it stops costing attempts.

Template

Content for one channel, addressed by id. content is free-form JSON: notifkit fills {{placeholders}} in every string and hands the result to the transport. Per-topic opt-outs match its topic list.

Workflow

A named sequence of steps that can span days. Unlike one-shot notify(), it saves progress after every step, so it survives restarts, deploys and crashes. Steps can send, sleep, or wait for an external event.

Transport (provider)

The adapter to the outside world, and the only part that knows Resend from FCM. You register transports on the server at startup; everything upstream deals in channels, not vendors.

The pipeline

Underneath, notifkit is five workers passing messages through Redis Streams, one job each. The API returns once the request is durably in the first stream; everything after is asynchronous.

What each stage actually does

Following one call through

Take the request from the quickstart:

await notifkit.notify({
  user: "usr_123",
  template: "welcome",
  channels: ["email"],
  data: { name: "Alice", company: "Acme" },
});

1. API hashes your bearer token, finds the project, checks the request rate limit, validates the body, and publishes notification.requested to the normal-priority inbound stream. You get 202 with a messageId, in a couple of milliseconds.
2. Enricher picks it up. One user, so no expansion. It loads usr_123's profile and contacts, reads the welcome template (topic: transactional), and emits one notification.enriched message per email address on file.
3. Engine checks the idempotency key, the transactional opt-out, that channels.email isn't false, the user's local time against quiet hours, and the hourly send count. All clear, it renders the template ({{name}} becomes Alice) and publishes notification.dispatched to the outbound stream.
4. Delivery finds the transport registered for email and calls send(). On success it emits delivery:delivered and queues a log row.
5. Events flushes that row into message_logs, which is what GET /v1/notifications/logs reads.

Two consequences

A rejected message does not raise an error

By the time a gate rejects a message, notify() has already returned 202. The message is dropped, a notification:skipped event fires with a reason, and the server logs it at info. Opting out is a normal outcome, so debugging usually starts in the server log, not your app's error handler.

Delivery is at-least-once

Messages are acknowledged only after successful processing. If a worker dies mid-flight, its message stays pending and a sibling reclaims it a minute later. The cost is the duplicate case: if a provider accepts your email but its response never reaches notifkit, the retry sends a second one. Idempotency guards catch common repeats, but not that one; plan for it wherever exactly-once matters.

A sixth noun, sort of: the campaign

A campaign is just a label, with no stored object or lifecycle. Pass campaign to notify() and every message the call fans out into is tagged, along with every open, click, bounce and unsubscribe the provider reports later.

The catch: attribution is decided at send time and can't be reconstructed later. The five nouns describe one notification's journey; the label is the only thing tying journeys to the same decision. See Segments & scheduling for the send side and the reference for the statistics it unlocks.

Next