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-appkey(e.g.marketing), multilingualname/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
categoryfield (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
| Path | Permission | Description |
|---|---|---|
GET/POST /v1/apps/{app_id}/categories | users:read / admin | Category list (each with its opted_out_users count) and creation |
PATCH/DELETE /v1/apps/{app_id}/categories/{id} | admin | Update; deletion also deletes user preferences (they revert to the default) |
GET /v1/apps/{app_id}/users/by/{label}/{value}/preferences | users:read | The user's effective preferences (data[]: category, channel, opted_in, explicit, source) + categories |
PUT …/preferences | users: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}/preferences | Dashboard (Audience → Categories, user detail → Preferences card) |
| SDK | GET/PUT /sdk/v1/apps/{appId}/preferences | Proof 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 becomesunsubscribed.- 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:
categoryselection; 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).
Companies (B2B accounts)
In B2B products, people belong to a company (an account or workspace): a billing reminder goes to the company's admin and a feature announcement to all of its users. In Pushizo a company is a separate object…
Suppression list
The email and SMS send-block list — reasons (bounce, complaint, STOP, manual, one-click), masked storage, API and dashboard management, the include_unsubscribed exception.