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.
The suppression list is a per-app list of email and SMS addresses that must not be sent to. Raw values are not stored: the address is normalized, a SHA-256 hash is kept, and it is displayed masked (a***e@pushizo.com). It is checked at the audience stage and at send time; a suppressed delivery is recorded with status suppressed and suppression_reason: suppression_list.
Reasons
reason | Source | Removal |
|---|---|---|
bounce | Hard bounce (SES/Resend/SMTP 550), Netgsm invalid number | Manual deletion (if the address was corrected) |
complaint | Spam complaint (feedback loop) | Manual; re-sending to an address that complained is not recommended |
unsubscribe_link | One-click List-Unsubscribe or the confirmation page | When the user re-subscribes, or manually |
stop | SMS STOP keyword | Automatically via SMS START |
manual | Added via the dashboard/API; can be time-limited with expires_at | Manually, or when it expires |
include_unsubscribed: true (transactional email only: password reset, receipt) ignores unsubscribe_link entries; bounce, complaint, stop and manual entries always apply.
API
GET /v1/apps/{app_id}/suppressions?channel=&reason=&value=&cursor=(users:read) — query an exact address withvalue; the response is masked.POST /v1/apps/{app_id}/suppressions{ "channel": "email" | "sms", "value": "ayse@pushizo.com", "reason"?: "manual", "expires_at"?: "2026-12-31T00:00:00Z", "note"?: "…" }(users:write).DELETE /v1/apps/{app_id}/suppressions/{id}(users:write).
Examples: API → Suppression list. In the server SDKs: hs.suppressions.list / create / remove.
Dashboard and behavior
- Audience → Suppression list: filter, add, delete; the count is tracked with the
suppression_entries_total{channel,reason}metric. - "Clear data" (app) keeps the suppression list; user deletion (KVKK) does not leave the address hash in the list, but a bounce/complaint entry may be recreated according to provider rules.
- Relationship with subscription status: bounce → subscription
invalid; complaint/one-click/STOP → subscriptionunsubscribedand the correspondingsubscription.*webhook.
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:…
Identity verification with JWT (SDK identity verification)
When you pass your user identity (external_id) to the SDK, proof is required to prevent impersonation of another user. There are two methods, selected in the app settings (ADR-0023 §9):