Outbound Messaging & Delivery Center Architecture
Inside Delivery Center (/delivery-center), you can manage transactional pass dispatches, segmented promotional campaigns, reusable Email Templates, opt-out suppression lists, and real-time delivery logs.
Passinstance orchestrates high-volume outbound messaging through asynchronous background job queues connected to managed EU email infrastructure (eu-central-1 Frankfurt), carrier SMS delivery for global SMS, or your encrypted Custom SMTP relay:
Email Templates & Canonical Placeholders
Reusable templates created in Delivery Center -> Templates (Email Template Engine) ensure consistent branding across transactional notifications, welcome messages, and pass recovery alerts.
Placeholder Syntax & Automatic Normalization
Passinstance enforces a single curly brace syntax: {placeholderName}. If your design team inputs Mustache or Handlebars-style double braces ({{passDownloadUrl}}), Passinstance's parser (normalizePlaceholders) automatically normalizes them to single braces before storage and rendering.
| Placeholder Token | Type | Technical Description & Rendered Value |
|---|---|---|
{passDownloadUrl} | Required | The canonical smart download link (passAccessUrl). Inspects recipient device context to stream Apple Wallet .pkpass or redirect to Google Wallet. |
{passUrl}, {passLink}, {smartLink} | Alias | Recognized legacy aliases automatically normalized to {passDownloadUrl}. |
{appleWalletUrl} | Platform Direct | Direct link serving the raw Apple Wallet .pkpass bundle (application/vnd.apple.pkpass). |
{googleWalletUrl} | Platform Direct | Direct Google Wallet save link (https://pay.google.com/gp/v/save/<jwt>). |
{walletButtonText} | Localized String | Localized button label (e.g. "Add to Wallet", "Zu Apple Wallet hinzufügen"). |
{firstName}, {lastName}, {name} | Contact | Recipient's name extracted from customer attributes. |
{passFlowLink} | Enrollment | Public registration link for the associated PassFlow (/f/:url). |
{unsubscribeLink} | Compliance | HMAC-signed one-click unsubscribe link (GET /email/unsubscribe/:token). |
{attributeName} | Custom Property | Any custom attribute key defined on the template (e.g. {membershipNumber}, {tier}, {balance}). |
RFC 8058 One-Click Unsubscribe Compliance
For marketing sendouts, Passinstance automatically injects RFC 8058 compliant email headers:
List-Unsubscribe: <https://api.passinstance.com/email/unsubscribe/{signedToken}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
This enables native "Unsubscribe" action buttons in Gmail, Apple Mail, and Yahoo Mail, preventing complaints and protecting your domain reputation.
Sendouts by Email or SMS: Delivery Center Workflow
To launch an outbound batch distribution campaign:
Step 1: Filter Your Audience
In Delivery Center -> New Campaign, select your pass template and apply segment filters:
-
Status Filter: Target active passes (
status = 'ACTIVE'). -
Uninstalled Filter (
onlyUninstalled: true): Target only customers who have not yet added their pass to a device (installedDevices === 0). -
Date Created Window: Target passes created within specific date ranges.
Step 2: Choose Delivery Rail
-
Email: Delivered via managed email delivery or your Custom SMTP relay.
-
SMS: Delivered via carrier SMS delivery to international E.164 mobile numbers.
Step 3: Select or Compose Your Message
Choose a saved template from Delivery Center -> Templates or compose an ad-hoc message. Ensure {passDownloadUrl} is present in the email body.
Step 4: Run Preflight Estimation
Click Estimate Reach (POST /api/v1/email-campaigns/estimate). Passinstance analyzes your audience:
-
Total matching passes.
-
Valid email/phone records.
-
Suppressed contacts (excluded unsubscribes and hard bounces).
-
Required message credit balance.
Step 5: Dispatch or Schedule
Click Start Sendout (POST /api/v1/email-campaigns/:id/start) to begin immediate background processing via background job queue, or set a future publication date.
Delivery Pricing, Balance & Credit Top-Up
Outbound message delivery is billed on a transparent pay-as-you-go model:
| Channel | Platform Rate | Billing Unit | Notes |
|---|---|---|---|
| €0.0005 EUR | Per delivered email | Includes SES routing, bounce monitoring, and open tracking | |
| SMS | €0.03 EUR | Per 160-char GSM-7 segment | Global carrier SMS delivery mobile carrier routing |
| Push Updates | €0.00 (FREE) | Unlimited pushes | Apple APNs and Google Wallet pushes are always free |
Monitoring Balance & Purchasing Credits:
-
Check Balance: View your current balance in Delivery Center or via
GET /delivery/balance. -
Top-Up Credits: Click Add Balance (
POST /delivery/top-up). Passinstance opens a secure Stripe Checkout session allowing you to top up your account with credit card, SEPA, or bank transfer.
Sending Single Passes with Direct Email Delivery
When manually issuing a pass to an individual customer:
-
1
Navigate to Passes -> Create Individual Pass.
-
2
Enter the customer's attributes (
firstName,email, etc.). -
3
Check the "Send by Email" checkbox in the issuance modal.
-
4
Click Create Pass. Passinstance creates the pass record and immediately calls
POST /passes/:id/email/send, dispatching the personalized smart download link.
You can also trigger a single-pass email at any time from the pass detail view by clicking Quick Actions -> Send by Email (POST /passes/:passId/send-email-with-template).
Verified Custom SMTP Routing
If your workspace has configured a custom SMTP relay (AddonType.OWN_SMTP), all single-pass emails and campaign sendouts route through your own mail server instead of Passinstance's default SES infrastructure.
Troubleshooting: Email Template Not Sending (Why Does My Email Template Not Send?)
If an email fails to send during pass creation, manual dispatch, or campaign execution, the failure is caused by runtime gates enforced in sendout-runtime.gates.ts:
1. Missing Required {passDownloadUrl} Placeholder
If a template is marked as requiring a pass URL (requiresPassUrl), but the template content does not contain {passDownloadUrl} (or an accepted alias), the dispatch worker halts with BadRequestException. Fix: Edit the template in Delivery Center and add {passDownloadUrl} to the email body.
2. Customer Payment Method Gate (assertCustomerPaymentMethod)
Automated sendouts require that active workspaces have a verified payment method on file or a positive credit balance. If your subscription is past due or your credit balance is zero, the gateway throws PaymentRequiredException. Fix: Navigate to Settings -> Billing -> Payment Methods and update your card or top up credits.
3. Missing Recipient Contact Attributes
If the target pass record has a null or empty email field, the worker skips the pass and logs a validation error. Fix: Verify that the pass record contains a valid, well-formed email address.
4. Sendout Toggles Deactivated on Template
In Template Settings -> Distribution & Sendouts, verify that the relevant sendout mode is enabled:
-
adHocEmailEnabled === true(for manual quick sends). -
distributeOnCreate === true(for automated dispatch on pass generation). -
downloadPageEmailEnabled === true(for desktop forward-to-phone requests).
5. Empty Subject Line or Body
The preflight gate isManualPassEmailContentReady rejects messages where adHocEmailSubject or adHocEmailTemplate is blank.
SMS Sending Cost & Custom Sender Configuration
Understanding SMS Segment Costs
SMS messages are billed at €0.03 EUR per segment:
-
Standard GSM-7 Encoding: Up to 160 characters per segment.
-
Unicode / UCS-2 Encoding (Emojis, special accents): Up to 70 characters per segment.
-
Multi-segment Messages: Concatenated messages reserve 7 characters per segment for concatenation headers (153 characters for GSM-7, 67 for Unicode).
Pro Tip: Apple Wallet and Google Wallet push notifications are 100% free and unlimited. Send initial passes via SMS or email, and use push notifications (
changeMessage) for subsequent updates to eliminate messaging costs.
Configuring Alphanumeric Sender IDs
In Settings -> Messaging -> SMS Settings, you can configure your business name as the SMS Sender ID (senderProfile.smsSenderName, up to 11 alphanumeric characters):
-
Europe, UK, Australia & Most International Markets: Alphanumeric sender IDs are supported out-of-the-box without pre-registration. Customers see your company name (e.g.
MYBRAND) as the sender. -
United States & Canada: Telecommunication carriers strictly prohibit unregistered alphanumeric sender IDs. Messages to US/Canada are delivered via 10DLC compliant pooled numbers or dedicated short codes.
Why Passinstance Does Not Attach .pkpass Files Directly to Emails
Merchants frequently ask why Passinstance emails contain a smart link ({passDownloadUrl}) rather than attaching the raw .pkpass file directly to the email. There are three critical technical reasons:
1. Android Email Client Incompatibility (MIME Corruption)
Mobile email clients on Android (including the official Gmail and Outlook apps) do not recognize the Apple Wallet MIME type application/vnd.apple.pkpass. When an Android user taps a .pkpass attachment, the email client treats it as a raw .zip archive, displaying cryptic binary contents or an error stating "Cannot open file".
2. Google Wallet Architecture Requires Cloud JWT Links
Unlike Apple Wallet, Google Wallet cannot import local files. Google Wallet requires an authenticated cloud Add-to-Wallet URL (https://pay.google.com/gp/v/save/<signed_jwt>). By using smart links, Android users are automatically redirected to Google Wallet without friction.
3. Single-Device Security & Device Telemetry
A raw .pkpass file attached to an email can be forwarded to hundreds of unauthorized recipients. With smart download links:
-
You can enforce Single-Device Binding (
limitToOneActivePerPass). -
You can enforce PIN Protection and Expiration Dates (
enableDownloadUntil). -
You capture full Device Telemetry (operating system, browser, install timestamp, UTM attribution) when the pass is claimed.
Delivery REST API Reference
| Method | Endpoint Path | Auth Scope | Description |
|---|---|---|---|
| POST | /api/v1/passes/:id/send-email | API Key (passes) | Dispatches single pass transactional email using default template. |
| POST | /api/v1/passes/:passId/send-email-with-template | API Key (passes) | Sends single pass email with a specific templateId and idempotencyKey. |
| POST | /api/v1/passes/:passId/send-sms | API Key (passes) | Sends single pass SMS to recipient phoneNumber. |
| POST | /api/v1/email-campaigns | API Key (delivery) | Creates a draft batch sendout campaign. |
| POST | /api/v1/email-campaigns/estimate | API Key (delivery) | Returns audience size, deliverable pass count, and credit requirement. |
| POST | /api/v1/email-campaigns/:id/start | API Key (delivery) | Enqueues campaign for immediate background execution. |
| GET | /delivery/balance | API Key (billing) | Returns current prepaid messaging balance and currency. |
| POST | /delivery/top-up | API Key (billing) | Creates Stripe Checkout session to purchase message credits. |
| GET | /email-campaigns/track/:id/open | Public | Transparent tracking pixel recording email open timestamps. |
Related Documentation
-
Self-Service Distribution — PassFlows, smart links, QR codes, and NFC tags.
-
Download Links & PassFlow — Smart link routing, PIN protection, and PassFlow localization.
-
Your Own Sender Address & Custom SMTP — Complete guide to configuring custom SMTP relays.
-
Custom Branding & White-Label Options — Vanity domains and portal theming.
