PushizoDocs
Users & segments

Categories, user preferences and the preference center (Phase 12)

Manages which message categories users want to receive on which channel; campaigns/messages in a category are not sent to users who opted out of it. Design decisions: ADR-0019 §4, §13. Shared code:…

Manages which message categories users want to receive on which channel; campaigns/messages in a category are not sent to users who opted out of it. Design decisions: docs/adr/0019-ab-test-ve-tercihler.md. Shared code: packages/db/src/preferences.ts.

1. Data model

  • message_categories: per-app key (e.g. marketing), multilingual name/description, channels (null = all channels), default_opted_in, position.
  • user_preferences: user_id × channel (null = all) × category → opted_in, source (api, sdk, preference_center, dashboard, import). One record per (app_id, user_id, coalesce(channel,''), category).
  • Campaigns and messages carry a category field (campaigns.category, messages.category); journey sends do not inherit the category of the template/campaign — the category is set when the message is created.

Effective preference (effectiveOptIn): explicit per-channel record > "all channels" record > the category's default_opted_in value.

2. Suppression

During audience resolution (apps/worker/src/delivery/audience.ts), if the message has a category, categoryOptOuts fetches the users who opted out of that category (per channel); matching deliveries get status = suppressed, suppression_reason = category_opt_out. Acceptance criterion: a category opt-out suppresses campaigns in that category (ab-testing.int.test.ts, phase12.int.test.ts).

3. API

PathPermissionDescription
GET/POST /v1/apps/{app_id}/categoriesusers:read / adminCategory list (each with its opted_out_users count) and creation
PATCH/DELETE /v1/apps/{app_id}/categories/{id}adminUpdate; deletion also deletes user preferences (they revert to the default)
GET /v1/apps/{app_id}/users/by/{label}/{value}/preferencesusers:readThe user's effective preferences (data[]: category, channel, opted_in, explicit, source) + categories
PUT …/preferencesusers:write{ "preferences": [{ "category", "channel"?, "opted_in" }] }; undefined category 404, a channel the category does not cover 400
Internal/internal/v1/apps/{appId}/categories[…], /users/{userId}/preferencesDashboard (Audience → Categories, user detail → Preferences card)
SDKGET/PUT /sdk/v1/apps/{appId}/preferencesProof of ownership with subscription_id + token_hash (and identity_hash for logged-in users); Web Pushizo.User.getPreferences()/setPreferences([...])/getCategories(), Android/iOS/Flutter equivalents (docs/sdk/*.md)

Node: hs.preferences.listCategories/createCategory/updateCategory/deleteCategory/getUser/setUser; PHP: $hs->preferences->….

4. Preference center page

In email rendering, the {{ preference_center_url }} Liquid variable resolves to a signed per-delivery GET /t/p/{delivery_id}?a=&s= address (signature type p, packages/render/src/tracking.ts). The page is available in tr/en and light/dark themes; it lists the categories with checkboxes.

  • POST …/t/p/{delivery_id} action=save + cat_<key> fields: unchecked categories are turned off (source = preference_center).
  • action=unsubscribe_all: all categories are turned off and the delivery's email subscription becomes unsubscribed.
  • A wrong signature returns 404; GET never changes anything (safe for link scanners).

Branding is in apps.settings.preferenceCenter: enabled, brandName, accentColor, logoUrl, customUnsubscribeUrl. If a custom unsubscribe URL is set, the unsubscribe confirmation form (POST /t/u/{dlv} confirm=1) performs the action and then 302-redirects to customUnsubscribeUrl?delivery_id=…; RFC 8058 one-click (List-Unsubscribe=One-Click) returns 200 without a redirect.

5. SMS HELP / STOP auto-reply

In inbound SMS, HELP, INFO, YARDIM, BILGI/BİLGİ (SMS_HELP_KEYWORDS) → help; STOP keywords → stop. If apps.settings.sms.autoReply is on, the helpReply / stopReply text is sent to the single subscription as a transactional SMS (messages.source = api, include_unsubscribed: true, so it can be delivered even after STOP). The Twilio inbound webhook, the Netgsm inbox and the generic webhook (type: "help") use the same path (apps/api/src/hooks/hooks.service.ts autoReply). Dashboard: App settings → SMS replies.

6. Dashboard

  • Audience → Categories: list (opt-out count), create/edit/delete; tr/en name and description, channel selection, default opt-in.
  • User detail → Preferences: category × channel matrix showing the source and last update; changes made from the dashboard get source = dashboard.
  • Campaign / notification editor: category selection; the audience estimate takes category suppression into account.

7. Tests

apps/api/src/__tests__/phase12.int.test.ts (category CRUD, preference write/read, SDK preference endpoint, preference center page and custom unsubscribe URL, tenant isolation), apps/worker/src/__tests__/ab-testing.int.test.ts (category opt-out suppression), sdk/web/src/__tests__/faz12.test.ts (Web SDK preferences and collection prompt).

On this page