Skip to content
Helpcentrum-gids · Pass-distributieOnboardingfase 5
8 min leestijdGecontroleerd 2026-11-16

E-mail- & sms-bezorging

Gebruik het Bezorgcentrum, herbruikbare e-mailsjablonen, SES-bouncelogs en eigen SMTP-afzenders.

In deze gids

Interactieve UI-weergaven

Openen in onboardinggids (6 fasen)

Bekijk de exacte dashboardpanelen, knoppen en ingezoomde toelichtingen bij deze gids.

Ingezoomde UI-focus1 / 2
Belangrijke UI-onderdelen

Uitgiftelimieten & toegangscontroles (Ingesneden)

Configureer onbeperkte of beperkte uitgifte, toegangskanalen, Wallet-routering en beveiligingen zoals het blokkeren van opnieuw downloaden na activatie en het ontdubbelen van ontvangers.

Uitgaande berichten & architectuur van het Delivery Center

In het Delivery Center (/delivery-center) beheert u transactionele pasverzendingen, gesegmenteerde promotiecampagnes, herbruikbare E-mailsjablonen, uitschrijflijsten (suppressielijsten) en realtime bezorglogboeken.

Passinstance orkestreert grootschalige uitgaande berichten via asynchrone achtergrondwachtrijen die gekoppeld zijn aan beheerde EU-e-mailinfrastructuur (eu-central-1 Frankfurt), carrier-sms-bezorging voor wereldwijde sms of uw versleutelde eigen SMTP-relay:

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
VERZENDCONTROLES & MULTIKANAAL-BEZORGING
FASE 01 CAMPAGNE-OPSTELLING & PRE-FLIGHT
1
Doelgroepselectie: Filter op sjabloon, status (ACTIVE) of onlyUninstalled
2
Runtime-verzendcontroles (sendout-runtime.gates.ts):
assertCustomerPaymentMethod: Geldige betaalmethode of positief saldo
isManualPassEmailActive: Verzendschakelaar ingeschakeld op sjabloon
Placeholdercontrole: Vereist aanwezigheid van {passDownloadUrl}
3
Pre-flight schatting (POST/api/v1/email-campaigns/estimate)
FASE 02 ASYNCHRONE VERZENDWORKER & SJABLOONENGINE
Laadt e-mailsjabloon & normaliseert placeholders automatisch: {{...}}{...}
Vult {passDownloadUrl}, {appleWalletUrl}, {googleWalletUrl} in
Voegt HMAC-ondertekende {unsubscribeLink} & RFC 8058-headers toe
Handhaaft idempotencyKey-ontdubbeling per ontvangend pasrecord
FASE 03A E-MAILBEZORGGATEWAY
Beheerde EU-e-mailinfrastructuur (eu-central-1 Frankfurt)
Of versleutelde eigen SMTP-relay
Tarief: €0,0005 EUR per e-mail
FASE 03B SMS-BEZORGGATEWAY
Carrier-sms E.164-normalisatie
Ondersteuning alfanumerieke afzender-ID
Tarief: €0,03 EUR per sms-segment
FASE 04 FEEDBACKLOOP & SUPPRESSIEWEBHOOKS
SES SNS-bounces & klachten (/api/v1/webhooks/ses)automatische suppressie
Realtime open-trackingpixel (/email-campaigns/track/:id/open)
Bezorglogboeken & activiteitenstroom (GET/delivery/history)

E-mailsjablonen & canonieke placeholders

Herbruikbare sjablonen aangemaakt in Delivery Center -> Sjablonen (Email Template Engine) zorgen voor consistente huisstijl bij transactionele meldingen, welkomstberichten en herstelberichten voor passen.

Placeholdersyntaxis & automatische normalisatie

Passinstance hanteert een syntaxis met enkele accolades: {placeholderName}. Als uw ontwerpteam dubbele accolades in Mustache- of Handlebars-stijl gebruikt ({{passDownloadUrl}}), normaliseert de parser van Passinstance (normalizePlaceholders) deze automatisch naar enkele accolades vóór opslag en weergave.

Placeholder-tokenTypeTechnische beschrijving & gerenderde waarde
{passDownloadUrl}VerplichtDe canonieke slimme downloadlink (passAccessUrl). Herkent het apparaat van de ontvanger om een Apple Wallet .pkpass te streamen of door te sturen naar Google Wallet.
{passUrl}, {passLink}, {smartLink}AliasErkende verouderde aliassen die automatisch worden genormaliseerd naar {passDownloadUrl}.
{appleWalletUrl}Direct platformDirecte link die de ruwe Apple Wallet .pkpass-bundel aanbiedt (application/vnd.apple.pkpass).
{googleWalletUrl}Direct platformDirecte Google Wallet-opslaanlink (https://pay.google.com/gp/v/save/<jwt>).
{walletButtonText}Gelokaliseerde tekstGelokaliseerd knoplabel (bijv. "Add to Wallet", "Zu Apple Wallet hinzufügen").
{firstName}, {lastName}, {name}ContactNaam van de ontvanger uit de klantattributen.
{passFlowLink}InschrijvingOpenbare registratielink voor de gekoppelde PassFlow (/f/:url).
{unsubscribeLink}ComplianceHMAC-ondertekende afmeldlink met één klik (GET /email/unsubscribe/:token).
{attributeName}Aangepaste eigenschapElke aangepaste attribuutsleutel die op het sjabloon is gedefinieerd (bijv. {membershipNumber}, {tier}, {balance}).

RFC 8058-compliance voor afmelden met één klik

Voor marketingverzendingen voegt Passinstance automatisch RFC 8058-conforme e-mailheaders toe:

HTTP
List-Unsubscribe: <https://api.passinstance.com/email/unsubscribe/{signedToken}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Hierdoor verschijnen native knoppen voor "Uitschrijven" in Gmail, Apple Mail en Yahoo Mail, wat spamklachten voorkomt en uw domeinreputatie beschermt.


Verzendingen per e-mail of sms: workflow in het Delivery Center

Zo start u een uitgaande batchdistributiecampagne:

Stap 1: Filter uw doelgroep

Selecteer in Delivery Center -> Nieuwe campagne uw passjabloon en pas segmentfilters toe:

  • Statusfilter: Richt u op actieve passen (status = 'ACTIVE').
  • Filter voor niet-geïnstalleerde passen (onlyUninstalled: true): Bereik uitsluitend klanten die hun pas nog niet op een apparaat hebben toegevoegd (installedDevices === 0).
  • Aanmaakperiode: Richt u op passen die binnen specifieke datumbereiken zijn aangemaakt.

Stap 2: Kies het bezorgkanaal

  • E-mail: Verzonden via beheerde e-mailbezorging of uw eigen SMTP-relay.
  • Sms: Verzonden via carrier-sms-bezorging naar internationale E.164-mobiele nummers.

Stap 3: Kies of stel uw bericht op

Selecteer een opgeslagen sjabloon uit Delivery Center -> Sjablonen of stel een eenmalig bericht op. Zorg ervoor dat {passDownloadUrl} in de e-mailtekst staat.

Stap 4: Voer een pre-flight schatting uit

Klik op Bereik schatten (POST /api/v1/email-campaigns/estimate). Passinstance analyseert uw doelgroep:

  • Totaal aantal overeenkomende passen.
  • Geldige e-mail- of telefoonrecords.
  • Onderdrukte contacten (uitgesloten uitschrijvingen en hard bounces).
  • Vereist berichttegoedsaldo.

Stap 5: Verzenden of inplannen

Klik op Verzending starten (POST /api/v1/email-campaigns/:id/start) om direct achtergrondverwerking via de achtergrondwachtrij te starten, of stel een toekomstige verzenddatum in.


Bezorgtarieven, saldo & tegoed opwaarderen

Uitgaande berichtbezorging wordt transparant op basis van werkelijk verbruik gefactureerd:

KanaalPlatformtariefFactuureenheidOpmerkingen
E-mail€0,0005 EURPer bezorgde e-mailInclusief SES-routing, bouncebewaking en open-tracking
Sms€0,03 EURPer GSM-7-segment van 160 tekensWereldwijde carrier-sms-routing over mobiele netwerken
Pushupdates€0,00 (GRATIS)Onbeperkt aantal pushesPushmeldingen voor Apple APNs en Google Wallet zijn altijd gratis

Saldo bewaken & tegoed bijkopen:

  • Saldo bekijken: Bekijk uw huidige saldo in Delivery Center of via GET /delivery/balance.
  • Tegoed opwaarderen: Klik op Saldo toevoegen (POST /delivery/top-up). Passinstance opent een beveiligde Stripe Checkout-sessie waarmee u uw account kunt opwaarderen via creditcard, SEPA of bankoverschrijving.

Enkele passen verzenden met directe e-mailbezorging

Wanneer u handmatig een pas uitgeeft aan een individuele klant:

  1. 1
    Ga naar Passen -> Individuele pas aanmaken.
  2. 2
    Vul de klantattributen in (firstName, email, enz.).
  3. 3
    Vink in het uitgiftevenster het selectievakje "Verzenden per e-mail" aan.
  4. 4
    Klik op Pas aanmaken. Passinstance maakt het pasrecord aan en roept direct POST /passes/:id/email/send aan om de gepersonaliseerde slimme downloadlink te versturen.

U kunt ook op elk gewenst moment een e-mail voor een enkele pas versturen vanuit de pasdetailweergave via Snelle acties -> Verzenden per e-mail (POST /passes/:passId/send-email-with-template).

Geverifieerde eigen SMTP-routing

Als uw werkruimte een eigen SMTP-relay heeft geconfigureerd (AddonType.OWN_SMTP), worden alle enkelvoudige pas-e-mails en campagneverzendingen via uw eigen mailserver gerouteerd in plaats van via de standaard SES-infrastructuur van Passinstance.


Probleemoplossing: e-mailsjabloon wordt niet verzonden (waarom verstuurt mijn e-mailsjabloon niet?)

Als een e-mail niet wordt verzonden bij het aanmaken van een pas, handmatige verzending of campagne-uitvoering, wordt dit veroorzaakt door runtime-controles in sendout-runtime.gates.ts:

1. Ontbrekende verplichte placeholder {passDownloadUrl}

Als een sjabloon gemarkeerd is als vereisend voor een pas-URL (requiresPassUrl), maar de sjablooninhoud geen {passDownloadUrl} (of erkende alias) bevat, stopt de verzendworker met BadRequestException. Oplossing: Bewerk het sjabloon in het Delivery Center en voeg {passDownloadUrl} toe aan de e-mailtekst.

2. Betaalmethodecontrole voor de klant (assertCustomerPaymentMethod)

Voor geautomatiseerde verzendingen moet een actieve werkruimte beschikken over een geverifieerde betaalmethode of een positief berichttegoedsaldo. Als uw abonnement een betalingsachterstand heeft of uw saldo nul is, retourneert de gateway PaymentRequiredException. Oplossing: Ga naar Instellingen -> Facturatie -> Betaalmethoden en werk uw betaalkaart bij of waardeer uw tegoed op.

3. Ontbrekende contactattributen van de ontvanger

Als het doelpasrecord een leeg of null veld email heeft, slaat de worker de pas over en registreert een validatiefout. Oplossing: Controleer of het pasrecord een geldig, correct opgemaakt e-mailadres bevat.

4. Verzendschakelaars uitgeschakeld op het sjabloon

Controleer onder Sjablooninstellingen -> Distributie & verzendingen of de betreffende verzendmodus is ingeschakeld:

  • adHocEmailEnabled === true (voor handmatige snelle verzendingen).
  • distributeOnCreate === true (voor automatische verzending bij pasaanmaak).
  • downloadPageEmailEnabled === true (voor doorsturen-naar-telefoon vanaf desktop).

5. Lege onderwerpregel of inhoud

De pre-flight controle isManualPassEmailContentReady weigert berichten waarbij adHocEmailSubject of adHocEmailTemplate leeg is.


Sms-verzendkosten & eigen afzenderconfiguratie

Inzicht in kosten per sms-segment

Sms-berichten worden gefactureerd tegen €0,03 EUR per segment:

  • Standaard GSM-7-codering: Maximaal 160 tekens per segment.
  • Unicode / UCS-2-codering (emoji's, speciale accenten): Maximaal 70 tekens per segment.
  • Berichten met meerdere segmenten: Samengevoegde berichten reserveren 7 tekens per segment voor koppelingsheaders (153 tekens voor GSM-7, 67 voor Unicode).

Tip: Pushmeldingen voor Apple Wallet en Google Wallet zijn 100% gratis en onbeperkt. Verstuur de eerste pas via sms of e-mail en gebruik pushmeldingen (changeMessage) voor alle latere updates om berichtkosten weg te nemen.

Alfanumerieke afzender-ID's configureren

Onder Instellingen -> Berichten -> Sms-instellingen kunt u uw bedrijfsnaam instellen als sms-afzender-ID (senderProfile.smsSenderName, maximaal 11 alfanumerieke tekens):

  • Europa, VK, Australië & de meeste internationale markten: Alfanumerieke afzender-ID's worden standaard zonder voorafgaande registratie ondersteund. Klanten zien uw bedrijfsnaam (bijv. MIJNMERK) als afzender.
  • Verenigde Staten & Canada: Telecomproviders verbieden ongeregistreerde alfanumerieke afzender-ID's strikt. Berichten naar de VS en Canada worden bezorgd via 10DLC-conforme gepoolde nummers of dedicated shortcodes.

Waarom Passinstance geen .pkpass-bestanden rechtstreeks als e-mailbijlage toevoegt

Bedrijven vragen regelmatig waarom Passinstance-e-mails een slimme link ({passDownloadUrl}) bevatten in plaats van het ruwe .pkpass-bestand direct als bijlage mee te sturen. Daarvoor zijn drie cruciale technische redenen:

1. Incompatibiliteit van e-mailclients op Android (MIME-corruptie)

Mobiele e-mailapps op Android (waaronder de officiële apps van Gmail en Outlook) herkennen het Apple Wallet MIME-type application/vnd.apple.pkpass niet. Wanneer een Android-gebruiker op een .pkpass-bijlage tikt, behandelt de e-mailclient het bestand als een gewoon .zip-archief en toont cryptische binaire inhoud of de melding "Kan bestand niet openen".

In tegenstelling tot Apple Wallet kan Google Wallet geen lokale bestanden importeren. Google Wallet vereist een geauthenticeerde cloud-URL voor Toevoegen aan Wallet (https://pay.google.com/gp/v/save/<signed_jwt>). Dankzij slimme links worden Android-gebruikers probleemloos en automatisch doorgestuurd naar Google Wallet.

3. Beveiliging per apparaat & apparaattelemetrie

Een ruw .pkpass-bestand in een e-mailbijlage kan worden doorgestuurd naar honderden onbevoegde ontvangers. Met slimme downloadlinks:

  • Kunt u Koppeling aan één apparaat (limitToOneActivePerPass) afdwingen.
  • Kunt u Pincodebeveiliging en Vervaldatums (enableDownloadUntil) instellen.
  • Legt u volledige Apparaattelemetrie vast (besturingssysteem, browser, installatietijdstip, UTM-attributie) op het moment dat de pas wordt geclaimd.

REST API-referentie voor bezorging

MethodeEndpointpadAuth-bereikBeschrijving
POST/api/v1/passes/:id/send-emailAPI-sleutel (passes)Verstuurt een transactionele e-mail voor één pas met het standaardsjabloon.
POST/api/v1/passes/:passId/send-email-with-templateAPI-sleutel (passes)Verstuurt een e-mail voor één pas met een specifiek templateId en idempotencyKey.
POST/api/v1/passes/:passId/send-smsAPI-sleutel (passes)Verstuurt een sms voor één pas naar phoneNumber van de ontvanger.
POST/api/v1/email-campaignsAPI-sleutel (delivery)Maakt een conceptcampagne voor batchverzending aan.
POST/api/v1/email-campaigns/estimateAPI-sleutel (delivery)Retourneert de doelgroepgrootte, het aantal bezorgbare passen en het benodigde tegoed.
POST/api/v1/email-campaigns/:id/startAPI-sleutel (delivery)Plaatst de campagne in de wachtrij voor directe achtergrondverwerking.
GET/delivery/balanceAPI-sleutel (billing)Retourneert het huidige prepaid berichttegoed en de valuta.
POST/delivery/top-upAPI-sleutel (billing)Maakt een Stripe Checkout-sessie aan om berichttegoed bij te kopen.
GET/email-campaigns/track/:id/openOpenbaarTransparante trackingpixel die open-tijdstempels van e-mails registreert.

Gerelateerde documentatie

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.