Skip to content
palumb

Audience

Your audience is the set of people you can notify. Three entities model it: subscribers (who), topics (groups), and subscriptions (the link).

Subscriber

Section titled “Subscriber”

A subscriber is a recipient, addressed by your external_id — the user id in your own system, so you never store a palumb id. It carries:

  • contacts — a per-kind map of addresses, e.g. { email: ["ada@example.com"] }. The kind matches a channel kind; delivery reads the address from here.
  • locale (optional) — for rendering.
  • attributes (optional) — free-form JSON you can use when rendering.

Identify is an idempotent upsert

Section titled “Identify is an idempotent upsert”

PUT /v1/subscribers/:externalId creates or updates a subscriber. It is safe to call repeatedly, and it merges rather than replaces. The rules per contacts kind:

You sendResult for that kind
A non-empty listOverwrites the addresses
An empty list []Clears the kind
Omit the kind entirelySurvives unchanged

locale and attributes follow the same “provided overwrites, omitted keeps” shape. So PUT … { contacts: { sms: ["+39…"] } } adds an SMS contact without disturbing an existing email.

Topic

Section titled “Topic”

A topic is a pub/sub grouping keyed by a string (e.g. billing.invoices, oncall). A topic can be:

  • Created explicitly — PUT /v1/topics/:key, optionally with a name / description.
  • Born implicitly — the first time someone subscribes to a key that doesn’t exist yet, palumb creates the topic (key only). An implicit create never clobbers metadata you set explicitly.

Subscription

Section titled “Subscription”

A subscription is the subscriber ↔ topic link. It is what lets a trigger target a whole topic and fan out to everyone on it.

  • PUT /v1/subscribers/:externalId/subscriptions/:topicKey subscribes; re-subscribing is a no-op (the pair is unique).
  • The fan-out over multiple topics is deduplicated by subscriber external id — someone on several targeted topics is notified once.

Lifecycle & cascade

Section titled “Lifecycle & cascade”
  • Delete a subscriber (DELETE /v1/subscribers/:externalId) — its subscriptions are removed too (database-level cascade).
  • Delete a topic (DELETE /v1/topics/:key) — guarded: if any subscriber is still subscribed, the delete is rejected (409). Unsubscribe everyone first. This prevents silently orphaning subscriptions.
Section titled “Related”