Skip to content
Help Center Guide · Pass DistributionOnboarding Phase 5
8 min readVerified 2026-11-16

Email & SMS Delivery

Use Delivery Center Sendouts, reusable Email Templates, SES bounce monitoring, and custom SMTP sender configuration.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus1 / 2
Key UI elements

Issuance limits & Access controls (Zoomed)

Configure Unlimited or Limited issuance, Access channels, Wallet support & routing, and safeguards like 'Block re-download after activation' and 'Deduplicate campaign recipients'.

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:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SENDOUT GATES & MULTI-CHANNEL DISPATCH
STAGE 01 CAMPAIGN AUTHORING & PREFLIGHT
1
Audience Selection: Filter by template, status (ACTIVE), or onlyUninstalled
2
Sendout Runtime Gates Check (sendout-runtime.gates.ts):
assertCustomerPaymentMethod: Valid billing method or positive balance
isManualPassEmailActive: Sendout toggle enabled on template
Placeholder Check: Enforces presence of {passDownloadUrl}
3
Preflight Estimation (POST/api/v1/email-campaigns/estimate)
STAGE 02 ASYNC DISPATCH WORKER & TEMPLATE ENGINE
Ingests Email Template & auto-normalizes placeholders: {{...}}{...}
Hydrates {passDownloadUrl}, {appleWalletUrl}, {googleWalletUrl}
Injects HMAC-signed {unsubscribeLink} & RFC 8058 Unsubscribe Headers
Enforces idempotencyKey deduplication per recipient pass record
STAGE 03A EMAIL DELIVERY GATEWAY
managed EU email infrastructure (`eu-c
Or Encrypted Custom SMTP Relay
Rate: €0.0005 EUR per email
STAGE 03B SMS DELIVERY GATEWAY
ral-1` Frankfurt) | | - carrier SMS
Alphanumeric sender ID support
Rate: €0.03 EUR per SMS segment
STAGE 04 FEEDBACK LOOP & SUPPRESSION WEBHOOKS
SES SNS Bounces & Complaints (/api/v1/webhooks/ses)Auto-suppression
Real-time Open Tracking Pixel (/email-campaigns/track/:id/open)
Delivery Logs & Activity Stream (GET/delivery/history)

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 TokenTypeTechnical Description & Rendered Value
{passDownloadUrl}RequiredThe canonical smart download link (passAccessUrl). Inspects recipient device context to stream Apple Wallet .pkpass or redirect to Google Wallet.
{passUrl}, {passLink}, {smartLink}AliasRecognized legacy aliases automatically normalized to {passDownloadUrl}.
{appleWalletUrl}Platform DirectDirect link serving the raw Apple Wallet .pkpass bundle (application/vnd.apple.pkpass).
{googleWalletUrl}Platform DirectDirect Google Wallet save link (https://pay.google.com/gp/v/save/<jwt>).
{walletButtonText}Localized StringLocalized button label (e.g. "Add to Wallet", "Zu Apple Wallet hinzufügen").
{firstName}, {lastName}, {name}ContactRecipient's name extracted from customer attributes.
{passFlowLink}EnrollmentPublic registration link for the associated PassFlow (/f/:url).
{unsubscribeLink}ComplianceHMAC-signed one-click unsubscribe link (GET /email/unsubscribe/:token).
{attributeName}Custom PropertyAny 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:

HTTP
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:

ChannelPlatform RateBilling UnitNotes
Email€0.0005 EURPer delivered emailIncludes SES routing, bounce monitoring, and open tracking
SMS€0.03 EURPer 160-char GSM-7 segmentGlobal carrier SMS delivery mobile carrier routing
Push Updates€0.00 (FREE)Unlimited pushesApple 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. 1
    Navigate to Passes -> Create Individual Pass.
  2. 2
    Enter the customer's attributes (firstName, email, etc.).
  3. 3
    Check the "Send by Email" checkbox in the issuance modal.
  4. 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".

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

MethodEndpoint PathAuth ScopeDescription
POST/api/v1/passes/:id/send-emailAPI Key (passes)Dispatches single pass transactional email using default template.
POST/api/v1/passes/:passId/send-email-with-templateAPI Key (passes)Sends single pass email with a specific templateId and idempotencyKey.
POST/api/v1/passes/:passId/send-smsAPI Key (passes)Sends single pass SMS to recipient phoneNumber.
POST/api/v1/email-campaignsAPI Key (delivery)Creates a draft batch sendout campaign.
POST/api/v1/email-campaigns/estimateAPI Key (delivery)Returns audience size, deliverable pass count, and credit requirement.
POST/api/v1/email-campaigns/:id/startAPI Key (delivery)Enqueues campaign for immediate background execution.
GET/delivery/balanceAPI Key (billing)Returns current prepaid messaging balance and currency.
POST/delivery/top-upAPI Key (billing)Creates Stripe Checkout session to purchase message credits.
GET/email-campaigns/track/:id/openPublicTransparent tracking pixel recording email open timestamps.

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.