PushizoDocs
Messaging & campaigns

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.

ProviderChannelFields (secret ones in italics)Validation
smtpemailhost, port, secure (465 TLS / STARTTLS), username, password, sender fieldsSMTP EHLO + auth (verify)
sesemailregion, access_key_id, secret_access_key, configuration_set, sender fieldsGET /v2/email/account (SigV4)
resendemailapi_key, webhook_secret (whsec_…, optional), sender fieldsGET /domains (a send-only key is also accepted)
twiliosmsaccount_sid, auth_token, from_number (E.164 or alphanumeric) or messaging_service_sidGET /Accounts/{sid}.json
netgsmsmsusercode, password, msgheader, iys_filter (0/11/12)GET /sms/rest/v2/msgheader + header check
mockemail/smsoptional from_address, from_name for emailalways 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).

FieldDescription
email_subjectSubject (Liquid). Falls back to headings if absent.
email_mjmlMJML source (Liquid → MJML compilation). File access via mj-include is disabled.
email_bodyPrebuilt HTML (Liquid). Used if there is no MJML.
email_preheaderInbox preview text (hidden preheader).
email_from_name, email_from_address, email_reply_to_addressOverride the channel defaults.
disable_email_click_trackingLinks are not rewritten as redirects.
contentsSMS body (language selection + Liquid); for email, becomes the body in a plain template if there is no MJML/HTML.
sms_fromSender (number/header) override.
sms_media_urlsMMS 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_shorteningLinks in SMS are not converted to short links.
add_to_inbox, inbox_ttlAlso 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):

URLBehavior
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 send user.external_id (+ identity_hash), for an anonymous user the device's subscription ID user.subscription_id; the new subscription is linked to that user.
  • Numbers are stored in E.164 (+905321234567); spaces, hyphens, parentheses and the 00 prefix 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 Netgsm encoding: 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 OptOutType or keyword), the Netgsm inbox query or the generic webhook (type: "stop"|"start"). STOP → suppression stop + subscription unsubscribed; START → the stop entry is removed and the subscription becomes subscribed again. 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 webhook type: "help". When apps.settings.sms.autoReply is on, the helpReply / stopReply text 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 (subscription invalid), 15 → blacklist (stop suppression), everything else failed. Messages are sent only to +90 numbers.

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}.

ProviderSetupVerificationEvents handled
SESConfiguration set → SNS topic → HTTPS subscription to this URLSNS signature (SigningCertURL only sns.<region>.amazonaws.com), the topic (TopicArn) region must match the channel's SES region, the subscription is confirmed automaticallyBounce (Permanent → bounce, others soft), Complaint, Delivery, Open, Click, Reject
ResendWebhooks → endpoint = this URL; enter the signing secret in the channel settings as webhook_secretSvix signature (5 min tolerance)email.delivered/bounced/complained/opened/clicked/failed
TwilioStatusCallback is added automatically when sending; also enter the same URL as the number's A message comes in URLX-Twilio-Signature (auth token)delivered, undelivered/failed (+ ErrorCode), incoming STOP/START
Generic (smtp, mock)JSON POST from your own ESP/MTAURL tokenthe 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, read users.read, write users.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_seconds for banners.
  • Triggers (all must be satisfied): session_start, event (name), screen (name), trigger (key, op: eq|neq|exists|gt|lt, value). trigger conditions are compared against values set with InAppMessages.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_id is required for click).
  • SDK behavior: refreshes the list at session start and at most every 5 minutes; shows one message at a time (the highest priority); reports impression on display, click on a button and dismiss on close; remaining_impressions and min_interval_seconds are 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 at http://localhost:8025): save the email channel as smtp, host localhost (Mailpit may listen only on ::1), port 1025, 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 0001 are invalid, 0002 permanent error, 0003 transient error, 0004 rate limit, 0005 auth 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"}'.

On this page