​

Subscriptions

Most campaigns decide who to notify from the event: the buyer, the account owner, the person whose password expired. A subscription flips that around. Someone tells you, once, that they want to hear about a specific thing in your product — a project, a thread, a document, a build pipeline — and every later event about that thing reaches them. This page is the shared vocabulary: what a subscription is, what Notifizz keeps, and how one turns into a message. Developers will find the calls in the backend reference and the subscribe widget.

​

TL;DR

• A subscription is a link between a subscriber id (whoever your app says the current user is) and a resource id (whatever they chose to follow). Nothing more.
• People subscribe themselves, from your own interface, by clicking the subscribe button. That click is the consent record.
• Notifizz stores the two ids and a timestamp. No name, no email, unless your application explicitly supplies them.
• Unsubscribing deletes the record, display data included. There is no tombstone and no archive.
• A subscription becomes a notification when a campaign whose recipient is Subscribers receives an event carrying the resource id. Membership is resolved at notification time, never from a list inside the event.
• Subscriptions are not unsubscribe categories. A subscription says notify me about this thing; a category says how much promotional mail this address accepts.

​

What a subscription holds

One person can subscribe to any number of resources, and the pair (subscriber, resource) is unique: clicking subscribe twice produces one record, not two. Unsubscribing something that was never subscribed does nothing and reports success. Both ids are opaque strings minted by your application. Notifizz never parses them, never validates them against a list, and never invents one.

​

A resource is a group

The widget calls it a resourceId because that is what it means on the page — the card, the thread, the project that carries the button. On the campaign side the same value is called a group, because that is what it has become: the set of people who subscribed to it. They are the same string. proj_4a19f on the button is proj_4a19f in the event that later notifies its subscribers. Pick ids that are stable for the lifetime of the thing they name — renaming a project must not renumber its group, or its subscribers are silently orphaned.

​

Who subscribes, and how

Subscriptions are created by the person subscribing, through the subscribe widget embedded in your own interface. There is no import, no CSV, no admin screen that subscribes somebody on their behalf. That is a deliberate constraint rather than a missing feature. The click is the consent record: the person was signed in to your product, on the page of the thing they chose to follow, and they pressed the button. Nothing else in the chain has to reconstruct intent afterwards.

​

What Notifizz stores

Very little, and only for as long as the subscription lasts.

• The subscribe widget sends the subscriber id and nothing else. A subscription created from a page in your app carries no name, no address, no avatar.
• Display data exists in the record only if your application supplies it explicitly. When it does, it was collected with the same click.
• Unsubscribing deletes the row. The subscription and any display data attached to it disappear together — there is no soft delete, so a re-subscription later is a genuinely new record with a new timestamp.

This is the same posture as the rest of the platform: see privacy friendly for how Notifizz avoids holding a copy of your user base.

​

Reaching a subscriber on a channel

The consequence of storing so little is worth stating plainly: a subscriber id is not an address. Before a subscriber can receive an email, something has to turn that id into one. Two ways, both normal:

1. The id already is the identity the channel needs. If your app passes the signed-in user’s email as the subscriber id, an email campaign has what it needs. If it passes the same user id your notification-center widget authenticates with, the notification center has what it needs — see the identity note in recipients.
2. An enricher resolves it. The orchestrator hands your enricher the subscriber ids and gets back the addresses and the personalisation fields, live, at notification time. Nothing is copied into Notifizz beforehand.

Choose once, per channel, and stay consistent: recipient ids must be stable over time or a multi-message sequence loses track of the person mid-way.

​

From a subscription to a notification

Four things have to line up:

1. A campaign whose recipient is Subscribers. Notifizz provisions this recipient type for your organisation automatically once the subscribe widget is enabled; you pick it when configuring the campaign, like any other recipient.
2. An event that carries the resource id in one of its properties. Any event will do — your own project.comment_added is as good as the shortcut the SDKs ship. What matters is that a property holds the group id, or an array of them.
3. An orchestrator that has been generated since. The orchestrator is what reads that property and resolves the group; a campaign whose configuration changed after generation must be regenerated.
4. A way to reach each subscriber on the campaign’s channel, as described above.

The resolution itself happens at send time, on the members the group has at that moment. This is the same principle as enrichers, applied to audiences: Notifizz does not keep a materialised list waiting.

​

Never a list inside the event

It is tempting to compute the audience in your application and put it in the event payload. Notifizz refuses that shape on purpose, and the orchestrator is instructed to ask you which property carries the group id rather than accept a list of people. The reason is timing. A list built when the event fires is a snapshot of that instant, which may be minutes or hours before the message is actually rendered and sent — long enough for someone to have unsubscribed. Resolving from the group id at send time closes that window, and it keeps your application from having to know who is subscribed to anything.

​

Deduplication across groups

An event can name several groups at once — a comment on a document that belongs to two projects, a deployment that touches three services. Someone subscribed to more than one of them is resolved once, not once per group, and the notification records every group they matched. Without that rule, the person following your product most closely is exactly the person who gets three copies of the same message.

​

Point in time

Membership is normally resolved as of now. When your event carries an occurredAt — a replay, an offline batch, a history backfill — the group is resolved as it stood at that moment instead, so a catch-up run notifies the people who were actually following the resource back then rather than the people following it today. occurredAt cannot be in the future, beyond a small tolerance for clock drift: a value that has not happened yet would let a send target a state that does not exist. Omit it in the ordinary case, where you emit the event as the thing happens. One edge is worth knowing, because unsubscribing erases rather than archives: someone who unsubscribed and re-subscribed after the instant you are replaying is treated as not subscribed then. The record that would have proved otherwise was deleted, deliberately.

​

Subscriptions are not notification preferences

Two different mechanisms, both about consent, easy to confuse: They stack rather than override. A subscriber to proj_4a19f who has opted out of promotional mail still receives the transactional notifications about that project, and still does not receive the promotional ones. The consent check runs after the audience is resolved and before the mailing fans out — being in a group has never been permission to mail somebody.

​

FAQ

​

See also