Email, SMS, in-app messages and the notification inbox
Since Phase 10, Pushizo also sends on channels beyond push: email (SMTP, Amazon SES, Resend), SMS (Twilio, Netgsm), in-app messages and the notification inbox. This document covers setup, the API contract and…
Since Phase 10, Pushizo also sends on channels beyond push: email (SMTP, Amazon SES, Resend), SMS (Twilio, Netgsm), in-app messages and the notification inbox. This document summarizes setup, the API contract and behavior. Architecture decisions: docs/adr/0015-email-sms-inapp.md.
1. Channel setup
Dashboard App settings → Channels → Email / SMS, or PUT /internal/v1/apps/{app_id}/channels/{email|sms} (public: PUT /v1/apps/{app_id}/channels/{channel}, admin). Real providers are unconfigured after saving; Validate (POST …/channels/{channel}/validate) makes a test connection to the provider and sets the channel to active on success. Secret fields (password, API key, auth token) are stored with envelope encryption and never returned in any response; if left empty on update, the stored value is kept.
| Provider | Channel | Fields (secret ones in italics) | Validation |
|---|---|---|---|
smtp | host, port, secure (465 TLS / STARTTLS), username, password, sender fields | SMTP EHLO + auth (verify) | |
ses | region, access_key_id, secret_access_key, configuration_set, sender fields | GET /v2/email/account (SigV4) | |
resend | api_key, webhook_secret (whsec_…, optional), sender fields | GET /domains (a send-only key is also accepted) | |
twilio | sms | account_sid, auth_token, from_number (E.164 or alphanumeric) or messaging_service_sid | GET /Accounts/{sid}.json |
netgsm | sms | usercode, password, msgheader, iys_filter (0/11/12) | GET /sms/rest/v2/msgheader + header check |
mock | email/sms | optional from_address, from_name for email | always valid |
Sender fields (email): from_address (required), from_name, reply_to, postal_address (physical address shown in the footer). email_from_address / email_from_name / email_reply_to_address in the message content override the channel default.
Domain authentication (DKIM/SPF/DMARC): verify your sending domain with the provider; add the provider's include: value to your SPF record, add the CNAME/TXT records the provider gives you for DKIM, and publish DMARC with at least v=DMARC1; p=none; rua=mailto:…. Sending from an unverified domain is rejected by SES/Resend (auth → channel invalid).
2. Message content
POST /v1/notifications, campaign and template content all use the same schema. Select the channel in the target with target.channels: ["email"] / ["sms"]; multiple channels can be targeted together (each subscription is rendered with its own channel's fields).
| Field | Description |
|---|---|
email_subject | Subject (Liquid). Falls back to headings if absent. |
email_mjml | MJML source (Liquid → MJML compilation). File access via mj-include is disabled. |
email_body | Prebuilt HTML (Liquid). Used if there is no MJML. |
email_preheader | Inbox preview text (hidden preheader). |
email_from_name, email_from_address, email_reply_to_address | Override the channel defaults. |
disable_email_click_tracking | Links are not rewritten as redirects. |
contents | SMS body (language selection + Liquid); for email, becomes the body in a plain template if there is no MJML/HTML. |
sms_from | Sender (number/header) override. |
sms_media_urls | MMS media URLs (at most 10, https://). Twilio only; if the SMS channel is Netgsm, creation returns 422 and sending fails with MMS_NOT_SUPPORTED. |
disable_sms_link_shortening | Links in SMS are not converted to short links. |
add_to_inbox, inbox_ttl | Also adds the message to target users' notification inbox (validity in seconds). |
Direct addresses (legacy provider equivalent): target.email_to (email) and target.include_phone_numbers (E.164) send to the given addresses; for an address without a subscription, an anonymous user + subscription is created and added to the target as include_subscription_ids (the raw address is not stored in the message target). These fields explicitly target the corresponding channel (including SMS). An invalid address returns 400.
include_unsubscribed: true (transactional email only; password resets, receipts): unsubscribed email addresses are also targeted and the unsubscribe_link suppression entry is ignored; bounce, complaint, manual and STOP entries always apply. Push and SMS subscriptions are not affected.
For a message sent only by email, contents is not required; email_subject + email_mjml/email_body is enough.
If no channels are given (target.channels / campaign audience.channels empty), channels are inferred from the content: push channels if there is contents (or content_available), email if any email_* field is present. SMS is targeted only explicitly with channels: ["sms"]. This way, a push campaign doesn't reach email/SMS subscribers with push copy. The content for each targeted channel is validated at creation/send time (e.g. contents for SMS, subject + body for email); if anything is missing, 422 HS_CONTENT_INVALID.
In email HTML bodies, Liquid output is HTML-escaped (markup cannot be injected via user tags); if you intentionally need raw HTML, use {{ value | raw }}. The {{ unsubscribe_url }} variable resolves to a delivery-specific unsubscribe URL; if the template doesn't use it, a footer is added automatically (language: recipient's language, tr/en).
Preview: POST /internal/v1/apps/{app_id}/templates/render (channel: "email" → email.{subject, preheader, html, text}; channel: "sms" → sms.{body, encoding, segments, per_segment, non_gsm_characters, turkish_characters}).
3. Email tracking and unsubscribe
Every email gets delivery-specific URLs HMAC-signed with a key derived from MASTER_KEY (rooted at API_URL):
| URL | Behavior |
|---|---|
GET /t/o/{dlv}?a=&s= | 1×1 GIF; on the first request, opened (+ delivered if needed). If the signature is invalid, only the GIF is returned. |
GET /t/c/{dlv}?a=&u=&s= | The signature covers the target URL; if valid, a clicked record + 302. If the signature doesn't match, 404 (no open redirect). |
GET /t/u/{dlv}?a=&s= | Confirmation page (tr/en, light/dark); GET does not unsubscribe (so link scanners don't trigger it). |
POST /t/u/{dlv}?a=&s= | RFC 8058 one-click (List-Unsubscribe=One-Click) and the confirmation form: subscription unsubscribed, suppression unsubscribe_link. |
GET /t/s/{code} | SMS short link (8-character base62, 90 days): the click is counted, 302. |
Headers: List-Unsubscribe: <https://…/t/u/…>, List-Unsubscribe-Post: List-Unsubscribe=One-Click, X-HS-Delivery-Id. The plain-text version (text/plain) is generated from the HTML.
4. SMS
- SDKs add an email/SMS subscription with
POST /sdk/v1/apps/{app_id}/subscriptions(channel: "email"|"sms"): for a logged-in user they senduser.external_id(+identity_hash), for an anonymous user the device's subscription IDuser.subscription_id; the new subscription is linked to that user. - Numbers are stored in E.164 (
+905321234567); spaces, hyphens, parentheses and the00prefix are normalized on SDK/API registration, and an invalid value returns 400. - Segment counting: GSM-7 single part 160 / multi-part 153; UCS-2 70 / 67.
ş ğ ı İ çare outside GSM-7 and force the message into UCS-2 (the dashboard warns you). With Netgsmencoding: TR(Turkish single-shift table), these letters count as 2 septets: single part 155, multi-part 149. The number of parts sent is recorded in the delivery event (sent.detail.segments) and the message counter (counts.sms_segments). - STOP/START: the Twilio incoming message webhook (Advanced Opt-Out
OptOutTypeor keyword), the Netgsm inbox query or the generic webhook (type: "stop"|"start"). STOP → suppressionstop+ subscriptionunsubscribed; START → thestopentry is removed and the subscription becomessubscribedagain. Keywords:STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, İPTAL/IPTAL, RET, DUR/START, YES, UNSTOP, BAŞLA/BASLA. - HELP and auto-reply (Phase 12):
HELP, INFO, YARDIM, BILGI/BİLGİ→help; generic webhooktype: "help". Whenapps.settings.sms.autoReplyis on, thehelpReply/stopReplytext is sent to that single subscription as a transactional SMS (it is delivered even after STOP). Details: preferences.md §5. - Netgsm does not offer push webhooks: every minute, the worker queries active Netgsm channels' delivery reports (
/sms/rest/v2/report, last 72 hours) and incoming SMS (/sms/rest/v2/inbox). Report status 1 →delivered, 3 → invalid number (subscriptioninvalid), 15 → blacklist (stopsuppression), everything elsefailed. Messages are sent only to+90numbers.
5. Incoming provider webhooks
The URL is shown in the dashboard under Channels → Email/SMS → Webhook URL (it contains a secret token; viewing it is written to the audit log) and is rotated with Regenerate (the old URL returns 404 immediately). Format: {API_URL}/hooks/{email|sms}/{provider}/{token}.
| Provider | Setup | Verification | Events handled |
|---|---|---|---|
| SES | Configuration set → SNS topic → HTTPS subscription to this URL | SNS signature (SigningCertURL only sns.<region>.amazonaws.com), the topic (TopicArn) region must match the channel's SES region, the subscription is confirmed automatically | Bounce (Permanent → bounce, others soft), Complaint, Delivery, Open, Click, Reject |
| Resend | Webhooks → endpoint = this URL; enter the signing secret in the channel settings as webhook_secret | Svix signature (5 min tolerance) | email.delivered/bounced/complained/opened/clicked/failed |
| Twilio | StatusCallback is added automatically when sending; also enter the same URL as the number's A message comes in URL | X-Twilio-Signature (auth token) | delivered, undelivered/failed (+ ErrorCode), incoming STOP/START |
Generic (smtp, mock) | JSON POST from your own ESP/MTA | URL token | the body below |
Generic body: { "type": "delivered|bounced|soft_bounced|complained|opened|clicked|failed|unsubscribed|stop|start|help", "delivery_id"?: "dlv_…", "provider_message_id"?: "…", "address"?: "+90…", "url"?, "error_code"?, "error_message"? }.
Effects: bounce → delivery bounced, subscription invalid, suppression bounce, counts.bounced, the delivery.failed webhook (error_code: bounced) and subscription.invalidated; complaint → suppression complaint, subscription unsubscribed; a synchronous SMTP 550 also writes suppression bounce. A repeat of the same event doesn't increment the counters a second time.
6. Suppression list
Addresses that must not receive email/SMS; raw values are not stored (normalized + SHA-256 hash and a masked display such as a***e@pushizo.com). It is checked at the audience stage and at send time; a suppressed delivery is suppressed + suppression_reason: suppression_list.
GET /v1/apps/{app_id}/suppressions?channel=&reason=&value=(users:read),POST{ channel, value, reason?, expires_at?, note? }(users:write),DELETE /{id}.- Dashboard: Audience → Suppression list (internal
…/suppressions, readusers.read, writeusers.write). - Reasons:
bounce,complaint,manual,unsubscribe_link,stop. "Clear data" keeps the suppression list.
7. In-app messages
Dashboard Messages → In-App (internal …/in-app-messages; editing requires campaigns.create, publishing requires campaigns.send). There is no raw HTML; a message is made of blocks that the SDKs render with native components.
{
"name": "Sepet hatırlatma",
"triggers": [{ "kind": "event", "name": "cart_viewed" }],
"display": {
"layout": "modal",
"background_color": "#ffffff",
"text_color": "#18181b",
"dismissible": true,
"blocks": [
{ "type": "image", "url": "https://cdn.pushizo.com/sale.png" },
{ "type": "title", "text": { "tr": "Merhaba {{ user.tags.name }}", "en": "Hi {{ user.tags.name }}" } },
{ "type": "body", "text": { "tr": "Sepetin seni bekliyor", "en": "Your cart is waiting" } },
{ "type": "button", "id": "go", "text": { "tr": "Sepete git", "en": "Open cart" }, "action": { "type": "deeplink", "url": "myapp://cart" } }
]
},
"audience": { "included_segments": ["seg_…"], "excluded_segments": [] },
"frequency": { "max_impressions": 3, "min_interval_seconds": 86400, "stop_after_interaction": true },
"priority": 10,
"start_at": null,
"end_at": null
}- Layouts:
modal,banner_top,banner_bottom,fullscreen;auto_dismiss_secondsfor banners. - Triggers (all must be satisfied):
session_start,event(name),screen(name),trigger(key,op:eq|neq|exists|gt|lt,value).triggerconditions are compared against values set withInAppMessages.addTrigger(key, value)in the SDK. - Actions:
dismiss,url(http/https, browser),deeplink(app scheme),tags(writes tags to the user). - Audience: include/exclude segments; devices without push permission are included too (segment conditions are evaluated regardless of subscription status).
- Frequency: total impressions per user (per device for devices without an identity), time between two impressions, stop after interaction. Default
max_impressions: 1. - Statistics: impressions, clicks, dismissals, unique users, CTR.
SDK contract:
GET /sdk/v1/apps/{app_id}/in-app?subscription_id=→{ language, data: [{ id, priority, triggers, display{layout, background_color, text_color, dismissible, auto_dismiss_seconds, blocks[]}, remaining_impressions, min_interval_seconds, stop_after_interaction, last_impression_at, end_at }] }. Block texts are plain strings resolved to the user's language and personalized (title.text,body.text,button.text,image.alt).POST /sdk/v1/apps/{app_id}/in-app/{message_id}/events{ subscription_id, type: "impression"|"click"|"dismiss", button_id? }(button_idis required forclick).- SDK behavior: refreshes the list at session start and at most every 5 minutes; shows one message at a time (the highest priority); reports
impressionon display,clickon a button anddismisson close;remaining_impressionsandmin_interval_secondsare also enforced locally.
8. Notification inbox
For add_to_inbox: true messages, one item is created for each targeted (non-suppressed) user (heading/body in the user's language, app_url or url, big_picture, data). The same message is added to the same user only once; when inbox_ttl expires, the item is hidden and deleted during daily maintenance.
SDK endpoints (the subscription must belong to the user; identity_hash if the app requires identity verification):
GET /sdk/v1/apps/{app_id}/users/{user_id}/inbox?subscription_id=&identity_hash=&limit=&cursor=→{ data: [{ id, message_id, title, body, url, image_url, data, read, read_at, archived_at, expires_at, created_at }], unread_count, next_cursor, has_more }(newest first).POST …/inbox/{item_id}/read{ subscription_id, identity_hash? }→ the item.POST …/inbox/read-all{ subscription_id, identity_hash? }→{ updated, unread_count }.DELETE …/inbox/{item_id}?subscription_id=&identity_hash=→ archives it.
Public API (API key; read users:read, modify users:write; the user is selected by alias):
GET /v1/apps/{app_id}/users/by/{label}/{value}/inbox?include_archived=&limit=&cursor=POST …/inbox/{item_id}/read,POST …/inbox/read-all,DELETE …/inbox/{item_id}
In-app messages can also be managed via the public API: GET|POST /v1/apps/{app_id}/in-app-messages, GET|PATCH|DELETE …/{id}, POST …/{id}/status (read analytics:read, write admin).
Dashboard: Notification inbox in the user details (GET /internal/v1/apps/{app_id}/users/{user_id}/inbox?include_archived=).
9. Personal data
When a user is deleted, their inbox items (FK) and in-app impression records are deleted. The suppression list does not hold raw addresses. "Clear data" deletes in-app impressions, the inbox and short links; it keeps in-app message definitions and the suppression list.
10. Metrics
/metrics: messaging_feedback_total{source,type} (source: hook:ses, hook:resend, hook:twilio, hook:smtp, hook:mock, tracking, short_link, unsubscribe_link, netgsm; type: delivered, opened, clicked, bounced, soft_bounced, complained, failed, unsubscribed) and suppression_entries_total{channel,reason}.
11. Local development
- Mailpit (
smtp://localhost:1025, UI athttp://localhost:8025): save the email channel assmtp, hostlocalhost(Mailpit may listen only on::1), port1025,secure: false, empty username, then click Validate. - Mock email: addresses whose local part starts with
invalid/bounce→ permanent rejection,transient,rate,auth,fail,open(opened after 5 s). - Mock SMS: numbers ending in
0001are invalid,0002permanent error,0003transient error,0004rate limit,0005auth error; all others succeed. - Testing bounce/STOP with the generic webhook:
curl -X POST "$(webhook adresi)" -H 'content-type: application/json' -d '{"type":"stop","address":"+905320000111"}'.
User data and KVKK/GDPR
Privacy tools for end-user data — consent (requiresPrivacyConsent), data export and deletion endpoints, retention periods, anonymization, webhook and backup implications.
Sending notifications
POST /v1/notifications — targeting, multi-language content, channel-specific fields, scheduling and time zones, delivery policies (TTL, priority, frequency, quiet hours), idempotency, and querying status and deliveries.