Preferences & quiet hours

Users who feel spammed don't open the preference centre; they hit the spam button. notifkit enforces consent in the engine, before rendering, so no caller can skip it by forgetting a check.

The preferences object

Preferences are free-form JSON on the user record. Adding a topic needs no migration: invent one and use it.

await notifkit.updateUser("usr_123", {
  timezone: "Asia/Tokyo",           // quiet hours are evaluated here
  preferences: {
    channels: {                     // false = never use this channel
      email: true,
      push: true,
      sms: false,
    },
    topics: {                       // false = opted out of this topic
      transactional: true,
      productUpdates: true,
      marketing: false,
    },
    quietHours: [                   // HH:MM, may wrap midnight
      { start: "22:00", end: "08:00" },
    ],
  },
});

curl -X PATCH http://localhost:3000/v1/users/usr_123 \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "Asia/Tokyo",
    "preferences": {
      "channels": { "email": true, "push": true, "sms": false, "slack": true, "whatsapp": true },
      "topics": {
        "transactional": true,
        "productUpdates": true,
        "marketing": false
      },
      "quietHours": [{ "start": "22:00", "end": "08:00" }]
    }
  }'

Or use the dedicated endpoint, which replaces the whole preferences object:

curl -X PATCH http://localhost:3000/v1/users/usr_123/preferences \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channels":{"sms":false},"topics":{"marketing":false}}'

Five gates, in this order

Only quiet hours defers. The other four end the attempt on that channel, and since refusal isn't a delivery failure, they do not trigger fallback.

Topic opt-outs key on the template

This surprises people most: a topic opt-out matches the topic list on the template, not anything in the notify() call.

// Templates declare which topics they belong to.
await notifkit.syncTemplates({
  templates: [
    { id: "password-reset", channel: "email", content: { /* … */ } },              // no topic
    { id: "weekly-digest",  channel: "email", topic: ["marketing"], content: {} },  // opt-outable
    { id: "invoice",        channel: "email", topic: ["billing", "transactional"], content: {} },
  ],
});

# Templates declare which topics they belong to.
curl -X PUT http://localhost:3000/v1/templates \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templates": [
      { "id": "password-reset", "channel": "email", "content": {} },
      { "id": "weekly-digest", "channel": "email",
        "topic": ["marketing"], "content": {} },
      { "id": "invoice", "channel": "email",
        "topic": ["billing", "transactional"], "content": {} }
    ]
  }'

A user with topics.marketing === false never receives weekly-digest on any channel. invoice has two topics and is blocked if either is off. password-reset has no topic, so nothing can suppress it.

Quiet hours

Windows are 24-hour HH:MM pairs in the user's own timezone. A window ending before it starts wraps midnight, the common case.

Users can have several windows, say a lunch break as well as the night:

quietHours: [
  { start: "12:00", end: "13:00" },
  { start: "22:00", end: "08:00" },
]

Touching or overlapping windows are followed through: if one window's release time lands in another, the engine keeps walking forward until it's outside every window. A user with 08:00–12:00 and 12:00–18:00 is deferred once, to 18:00, not woken at noon and deferred again.

Per-user throttling

Regardless of user settings, the engine caps notifications per person per hour: a true sliding window in Redis, shared across worker processes and scoped per project so tenants can't throttle each other.

A throttled message is dropped, not queued, and emits notification:throttled with the current count. If you see it in normal operation, batch upstream rather than raising the ceiling.

server.on("notification:throttled", (recipientId, count) => {
  metrics.increment("notifkit.throttled", { recipientId, count });
});

Per-contact opt-outs

Preferences can also attach to one contact instead of the whole user, say when someone wants receipts at their work address but not their personal one.

curl -X POST http://localhost:3000/v1/users/usr_123/contacts \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "target": "[email protected]",
    "preferences": { "optedOut": true }
  }'

A contact marked optedOut is skipped; the user's other addresses on that channel still receive the message.

Unsubscribes from the provider side

When a transport implements parseWebhook, provider events (unsubscribed, bounced, complained, opened, clicked) are matched to the original message and recorded in message_logs against its task. Query them alongside delivery attempts:

curl -s "http://localhost:3000/v1/notifications/logs?status=bounced&limit=50" \
  -H "Authorization: Bearer $NK_KEY"

Three trigger action: unsubscribed, complained or a hard bounced adds the address to the suppression list, and every later send drops it before dispatch. Soft bounces (a full mailbox, a transient outage) don't suppress; the address is still good.

# What has been suppressed, and why
curl -s "http://localhost:3000/v1/suppressions?limit=100" -H "Authorization: Bearer $NK_KEY"

Opens and clicks are recorded but never acted on: they're reporting signal, surfaced through campaign stats, never turned into preference changes.

One-click unsubscribe

Set PUBLIC_URL and UNSUBSCRIBE_SECRET and every email whose template has a topic carries List-Unsubscribe headers, so inboxes show a real unsubscribe button. Gmail and Yahoo have required this on bulk mail since early 2024.

The link is scoped to its source: clicking switches off the topics on that template for that user, leaving everything else (password resets, receipts) working. That's why only topic-bearing mail gets the header: a template with no topic is transactional by convention, has nothing to scope an opt-out to, and shouldn't offer to switch itself off.

Reading current state

# Just the preferences
curl -s http://localhost:3000/v1/users/usr_123/preferences -H "Authorization: Bearer $NK_KEY"

# User with contacts
curl -s http://localhost:3000/v1/users/usr_123 -H "Authorization: Bearer $NK_KEY"

# Contacts only
curl -s http://localhost:3000/v1/users/usr_123/contacts -H "Authorization: Bearer $NK_KEY"

Build a preference centre on these. Render checkboxes from GET /preferences, save with PATCH /preferences, and the engine uses the change on the next send. Template caches are invalidated across processes over Redis pub/sub, and user data is read fresh per message.