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:
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-token | Type | Technische beschrijving & gerenderde waarde |
|---|---|---|
{passDownloadUrl} | Verplicht | De 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} | Alias | Erkende verouderde aliassen die automatisch worden genormaliseerd naar {passDownloadUrl}. |
{appleWalletUrl} | Direct platform | Directe link die de ruwe Apple Wallet .pkpass-bundel aanbiedt (application/vnd.apple.pkpass). |
{googleWalletUrl} | Direct platform | Directe Google Wallet-opslaanlink (https://pay.google.com/gp/v/save/<jwt>). |
{walletButtonText} | Gelokaliseerde tekst | Gelokaliseerd knoplabel (bijv. "Add to Wallet", "Zu Apple Wallet hinzufügen"). |
{firstName}, {lastName}, {name} | Contact | Naam van de ontvanger uit de klantattributen. |
{passFlowLink} | Inschrijving | Openbare registratielink voor de gekoppelde PassFlow (/f/:url). |
{unsubscribeLink} | Compliance | HMAC-ondertekende afmeldlink met één klik (GET /email/unsubscribe/:token). |
{attributeName} | Aangepaste eigenschap | Elke 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:
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:
| Kanaal | Platformtarief | Factuureenheid | Opmerkingen |
|---|---|---|---|
| €0,0005 EUR | Per bezorgde e-mail | Inclusief SES-routing, bouncebewaking en open-tracking | |
| Sms | €0,03 EUR | Per GSM-7-segment van 160 tekens | Wereldwijde carrier-sms-routing over mobiele netwerken |
| Pushupdates | €0,00 (GRATIS) | Onbeperkt aantal pushes | Pushmeldingen 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
Ga naar Passen -> Individuele pas aanmaken.
-
2
Vul de klantattributen in (
firstName,email, enz.). -
3
Vink in het uitgiftevenster het selectievakje "Verzenden per e-mail" aan.
-
4
Klik op Pas aanmaken. Passinstance maakt het pasrecord aan en roept direct
POST /passes/:id/email/sendaan 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".
2. Google Wallet vereist cloud-JWT-links
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
| Methode | Endpointpad | Auth-bereik | Beschrijving |
|---|---|---|---|
| POST | /api/v1/passes/:id/send-email | API-sleutel (passes) | Verstuurt een transactionele e-mail voor één pas met het standaardsjabloon. |
| POST | /api/v1/passes/:passId/send-email-with-template | API-sleutel (passes) | Verstuurt een e-mail voor één pas met een specifiek templateId en idempotencyKey. |
| POST | /api/v1/passes/:passId/send-sms | API-sleutel (passes) | Verstuurt een sms voor één pas naar phoneNumber van de ontvanger. |
| POST | /api/v1/email-campaigns | API-sleutel (delivery) | Maakt een conceptcampagne voor batchverzending aan. |
| POST | /api/v1/email-campaigns/estimate | API-sleutel (delivery) | Retourneert de doelgroepgrootte, het aantal bezorgbare passen en het benodigde tegoed. |
| POST | /api/v1/email-campaigns/:id/start | API-sleutel (delivery) | Plaatst de campagne in de wachtrij voor directe achtergrondverwerking. |
| GET | /delivery/balance | API-sleutel (billing) | Retourneert het huidige prepaid berichttegoed en de valuta. |
| POST | /delivery/top-up | API-sleutel (billing) | Maakt een Stripe Checkout-sessie aan om berichttegoed bij te kopen. |
| GET | /email-campaigns/track/:id/open | Openbaar | Transparante trackingpixel die open-tijdstempels van e-mails registreert. |
Gerelateerde documentatie
-
Selfservice-distributie — PassFlows, slimme links, QR-codes en NFC-tags.
-
Downloadlinks & PassFlow — Slimme linkrouting, pincodebeveiliging en PassFlow-lokalisatie.
-
Uw eigen afzenderadres & aangepaste SMTP — Complete handleiding voor het configureren van eigen SMTP-relays.
-
Eigen huisstijl & white-labelopties — Eigen downloaddomeinen en portaalthema's.
