Architektur für ausgehende Nachrichten & das Delivery Center
Im Delivery Center (/delivery-center) verwalten Sie transaktionale Pass-Versendungen, segmentierte Werbekampagnen, wiederverwendbare E-Mail-Vorlagen, Abmelde- und Sperrlisten sowie Echtzeit-Zustellungsprotokolle.
Passinstance orchestriert ausgehende Nachrichten mit hohem Volumen über asynchrone Hintergrund-Job-Queues, die an unsere verwaltete EU-E-Mail-Infrastruktur (eu-central-1 Frankfurt), die Carrier-SMS-Zustellung für weltweiten SMS-Versand oder Ihren verschlüsselten benutzerdefinierten SMTP-Relay angebunden sind:
E-Mail-Vorlagen & kanonische Platzhalter
Wiederverwendbare Vorlagen unter Delivery Center -> Vorlagen (Email Template Engine) sorgen für ein einheitliches Branding über transaktionale Benachrichtigungen, Willkommens-E-Mails und Pass-Wiederherstellungshinweise hinweg.
Platzhalter-Syntax & automatische Normalisierung
Passinstance verwendet einfache geschweifte Klammern: {placeholderName}. Falls Ihr Designteam doppelte geschweifte Klammern im Mustache- oder Handlebars-Stil ({{passDownloadUrl}}) einträgt, normalisiert der Passinstance-Parser (normalizePlaceholders) diese vor der Speicherung und Ausgabe automatisch auf einfache Klammern.
| Platzhalter-Token | Typ | Technische Beschreibung & gerenderter Wert |
|---|---|---|
{passDownloadUrl} | Erforderlich | Der kanonische Smart-Download-Link (passAccessUrl). Erkennt den Gerätekontext des Empfängers, um Apple-Wallet-.pkpass-Dateien auszuliefern oder zu Google Wallet weiterzuleiten. |
{passUrl}, {passLink}, {smartLink} | Alias | Unterstützte Legacy-Aliase, die automatisch auf {passDownloadUrl} normalisiert werden. |
{appleWalletUrl} | Plattform-Direktlink | Direktlink zur Auslieferung des nativen Apple-Wallet-.pkpass-Pakets (application/vnd.apple.pkpass). |
{googleWalletUrl} | Plattform-Direktlink | Direkter Google-Wallet-Speicherlink (https://pay.google.com/gp/v/save/<jwt>). |
{walletButtonText} | Lokalisierter Text | Lokalisierte Schaltflächenbeschriftung (z. B. „Add to Wallet“, „Zu Apple Wallet hinzufügen“). |
{firstName}, {lastName}, {name} | Kontakt | Name des Empfängers aus den Kundenattributen. |
{passFlowLink} | Registrierung | Öffentlicher Registrierungslink des zugehörigen PassFlows (/f/:url). |
{unsubscribeLink} | Compliance | HMAC-signierter Ein-Klick-Abmeldelink (GET /email/unsubscribe/:token). |
{attributeName} | Benutzerdefiniertes Feld | Jeder benutzerdefinierte Attributschlüssel der Vorlage (z. B. {membershipNumber}, {tier}, {balance}). |
Ein-Klick-Abmeldung gemäß RFC 8058
Bei Marketing-Versendungen fügt Passinstance automatisch RFC-8058-konforme E-Mail-Header ein:
List-Unsubscribe: <https://api.passinstance.com/email/unsubscribe/{signedToken}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Dies aktiviert native „Abmelden“-Schaltflächen in Gmail, Apple Mail und Yahoo Mail, reduziert Spam-Beschwerden und schützt die Reputation Ihrer Domain.
Versandaktionen per E-Mail oder SMS: Delivery-Center-Workflow
So starten Sie eine ausgehende Stapelversand-Kampagne:
Schritt 1: Zielgruppe filtern
Wählen Sie unter Delivery Center -> Neue Kampagne Ihre Pass-Vorlage aus und wenden Sie Segmentfilter an:
-
Statusfilter: Beschränkt den Versand auf aktive Pässe (
status = 'ACTIVE'). -
Nicht-installiert-Filter (
onlyUninstalled: true): Adressiert ausschließlich Kundinnen und Kunden, die ihren Pass noch keinem Gerät hinzugefügt haben (installedDevices === 0). -
Erstellungszeitraum: Filtert nach Pässen, die innerhalb eines bestimmten Datumsbereichs erstellt wurden.
Schritt 2: Versandkanal wählen
-
E-Mail: Zustellung über die verwaltete E-Mail-Zustellung oder Ihren benutzerdefinierten SMTP-Relay.
-
SMS: Zustellung über die Carrier-SMS-Zustellung an internationale Mobilfunknummern im E.164-Format.
Schritt 3: Nachricht auswählen oder verfassen
Wählen Sie eine gespeicherte Vorlage unter Delivery Center -> Vorlagen oder verfassen Sie eine Ad-hoc-Nachricht. Stellen Sie sicher, dass {passDownloadUrl} im E-Mail-Text enthalten ist.
Schritt 4: Vorab-Reichweitenschätzung ausführen
Klicken Sie auf Reichweite schätzen (POST /api/v1/email-campaigns/estimate). Passinstance analysiert Ihre Zielgruppe und berechnet:
-
Gesamtzahl passender Pässe.
-
Gültige E-Mail-/Telefon-Datensätze.
-
Gesperrte Kontakte (ausgeschlossene Abmeldungen und Hard Bounces).
-
Erforderliches Nachrichtenguthaben.
Schritt 5: Sofort versenden oder planen
Klicken Sie auf Versand starten (POST /api/v1/email-campaigns/:id/start), um die sofortige Hintergrundverarbeitung über die Hintergrund-Job-Queue anzustoßen, oder legen Sie ein zukünftiges Versanddatum fest.
Versandpreise, Guthaben & Aufladung
Der ausgehende Nachrichtenversand wird transparent nutzungsbasiert (Pay-as-you-go) abgerechnet:
| Kanal | Plattformtarif | Abrechnungseinheit | Hinweise |
|---|---|---|---|
| 0,0005 € EUR | Pro zugestellter E-Mail | Inklusive SES-Routing, Bounce-Überwachung und Öffnungs-Tracking | |
| SMS | 0,03 € EUR | Pro GSM-7-Segment (160 Zeichen) | Weltweites Mobilfunk-Carrier-Routing über Carrier-SMS-Zustellung |
| Push-Updates | 0,00 € (KOSTENLOS) | Unbegrenzte Pushs | Apple-APNs- und Google-Wallet-Pushs sind stets kostenlos |
Guthaben überwachen & aufladen:
-
Guthaben prüfen: Sehen Sie Ihr aktuelles Guthaben im Delivery Center oder über
GET /delivery/balanceein. -
Guthaben aufladen: Klicken Sie auf Guthaben hinzufügen (
POST /delivery/top-up). Passinstance öffnet eine sichere Stripe-Checkout-Sitzung, über die Sie Ihr Konto per Kreditkarte, SEPA oder Überweisung aufladen können.
Einzelne Pässe direkt per E-Mail versenden
Wenn Sie manuell einen Pass für eine einzelne Kundin oder einen einzelnen Kunden ausstellen:
-
1
Navigieren Sie zu Pässe -> Einzelnen Pass erstellen.
-
2
Geben Sie die Kundenattribute ein (
firstName,emailusw.). -
3
Aktivieren Sie im Ausgabedialog das Kontrollkästchen „Per E-Mail senden“.
-
4
Klicken Sie auf Pass erstellen. Passinstance legt den Pass-Datensatz an, ruft umgehend
POST /passes/:id/email/sendauf und versendet den personalisierten Smart-Download-Link.
Sie können eine Einzelpass-E-Mail jederzeit auch direkt aus der Pass-Detailansicht über Schnellaktionen -> Per E-Mail senden (POST /passes/:passId/send-email-with-template) auslösen.
Verifiziertes Routing über eigenes SMTP
Wenn in Ihrem Workspace ein benutzerdefinierter SMTP-Relay (AddonType.OWN_SMTP) konfiguriert ist, laufen sämtliche Einzelpass-E-Mails und Kampagnenversendungen über Ihren eigenen Mailserver statt über die standardmäßige SES-Infrastruktur von Passinstance.
Fehlerbehebung: E-Mail-Vorlage wird nicht gesendet (Warum wird meine E-Mail-Vorlage nicht versendet?)
Schlägt der E-Mail-Versand bei der Pass-Erstellung, beim manuellen Versand oder bei einer Kampagne fehl, liegt dies an Laufzeitprüfungen in sendout-runtime.gates.ts:
1. Fehlender Pflicht-Platzhalter {passDownloadUrl}
Ist eine Vorlage so konfiguriert, dass sie eine Pass-URL erfordert (requiresPassUrl), enthält der Inhalt jedoch weder {passDownloadUrl} noch einen zulässigen Alias, bricht der Versand-Worker mit BadRequestException ab. Lösung: Bearbeiten Sie die Vorlage im Delivery Center und fügen Sie {passDownloadUrl} in den E-Mail-Text ein.
2. Prüfung der Kundenzahlungsmethode (assertCustomerPaymentMethod)
Automatisierte Versandaktionen setzen voraus, dass für aktive Workspaces eine verifizierte Zahlungsmethode hinterlegt ist oder ein positives Guthaben besteht. Bei überfälligem Abonnement oder leerem Guthaben wirft das Gateway PaymentRequiredException. Lösung: Gehen Sie zu Einstellungen -> Abrechnung -> Zahlungsmethoden und aktualisieren Sie Ihre Karte oder laden Sie Guthaben auf.
3. Fehlende Empfänger-Kontaktdaten
Ist das Feld email im Ziel-Pass-Datensatz leer oder null, überspringt der Worker den Pass und protokolliert einen Validierungsfehler. Lösung: Stellen Sie sicher, dass im Pass-Datensatz eine gültige, korrekt formatierte E-Mail-Adresse hinterlegt ist.
4. Versand-Schalter in der Vorlage deaktiviert
Prüfen Sie unter Vorlageneinstellungen -> Verteilung & Versand, ob der gewünschte Versandmodus aktiviert ist:
-
adHocEmailEnabled === true(für manuelle Schnellversendungen). -
distributeOnCreate === true(für automatischen Versand bei Pass-Erstellung). -
downloadPageEmailEnabled === true(für „An Mobilgerät senden“-Anfragen von der Desktop-Downloadseite).
5. Leere Betreffzeile oder leerer Nachrichtentext
Die Vorabprüfung isManualPassEmailContentReady lehnt Nachrichten ab, bei denen adHocEmailSubject oder adHocEmailTemplate leer ist.
SMS-Versandkosten & benutzerdefinierte Absenderkennung
SMS-Segmentkosten verstehen
SMS-Nachrichten werden mit 0,03 € EUR pro Segment abgerechnet:
-
Standard-GSM-7-Kodierung: Bis zu 160 Zeichen pro Segment.
-
Unicode- / UCS-2-Kodierung (Emojis, besondere Akzente): Bis zu 70 Zeichen pro Segment.
-
Mehrteilige Nachrichten: Verkettete SMS reservieren 7 Zeichen pro Segment für Verkettungs-Header (153 Zeichen bei GSM-7, 67 Zeichen bei Unicode).
Profi-Tipp: Push-Mitteilungen in Apple Wallet und Google Wallet sind 100 % kostenlos und unbegrenzt. Senden Sie den initialen Pass per SMS oder E-Mail und nutzen Sie für alle nachfolgenden Aktualisierungen Push-Mitteilungen (
changeMessage), um laufende Versandkosten zu vermeiden.
Alphanumerische Absenderkennungen konfigurieren
Unter Einstellungen -> Nachrichten -> SMS-Einstellungen können Sie Ihren Unternehmensnamen als SMS-Absenderkennung hinterlegen (senderProfile.smsSenderName, bis zu 11 alphanumerische Zeichen):
-
Europa, Vereinigtes Königreich, Australien & die meisten internationalen Märkte: Alphanumerische Absenderkennungen funktionieren ohne vorherige Registrierung. Kundinnen und Kunden sehen Ihren Markennamen (z. B.
MYBRAND) als Absender. -
USA & Kanada: Mobilfunkbetreiber untersagen nicht registrierte alphanumerische Absenderkennungen strikt. Nachrichten in die USA und nach Kanada werden über 10DLC-konforme gepoolte Rufnummern oder dedizierte Kurzwahlen zugestellt.
Warum Passinstance .pkpass-Dateien nicht direkt an E-Mails anhängt
Händler fragen häufig, warum Passinstance-E-Mails einen Smart-Link ({passDownloadUrl}) enthalten, statt die rohe .pkpass-Datei direkt anzuhängen. Dafür gibt es drei entscheidende technische Gründe:
1. Inkompatibilität von Android-E-Mail-Apps (MIME-Fehler)
Mobile E-Mail-Clients auf Android (einschließlich der offiziellen Gmail- und Outlook-Apps) erkennen den Apple-Wallet-MIME-Typ application/vnd.apple.pkpass nicht. Tippt eine Android-Nutzerin oder ein Android-Nutzer auf einen .pkpass-Anhang, behandelt die Mail-App die Datei als rohes .zip-Archiv und zeigt unleserliche Binärinhalte oder die Fehlermeldung „Datei kann nicht geöffnet werden“ an.
2. Google-Wallet-Architektur erfordert Cloud-JWT-Links
Anders als Apple Wallet kann Google Wallet keine lokalen Dateien importieren. Google Wallet verlangt eine authentifizierte Cloud-URL zum Speichern (https://pay.google.com/gp/v/save/<signed_jwt>). Über Smart-Links werden Android-Nutzende ohne Medienbruch direkt zu Google Wallet weitergeleitet.
3. Einzelgeräte-Sicherheit & Gerätetelemetrie
Eine als E-Mail-Anhang verschickte .pkpass-Datei lässt sich problemlos an Hunderte unbefugte Empfänger weiterleiten. Mit Smart-Download-Links können Sie hingegen:
-
Einzelgeräte-Bindung erzwingen (
limitToOneActivePerPass). -
PIN-Schutz und Ablaufdaten für Downloads durchsetzen (
enableDownloadUntil). -
Vollständige Gerätetelemetrie (Betriebssystem, Browser, Installationszeitstempel, UTM-Attribution) beim Abruf des Passes erfassen.
REST-API-Referenz für die Zustellung
| Methode | Endpunkt-Pfad | Auth-Scope | Beschreibung |
|---|---|---|---|
| POST | /api/v1/passes/:id/send-email | API-Schlüssel (passes) | Sendet eine transaktionale Einzelpass-E-Mail mit der Standardvorlage. |
| POST | /api/v1/passes/:passId/send-email-with-template | API-Schlüssel (passes) | Sendet eine Einzelpass-E-Mail mit spezifischer templateId und idempotencyKey. |
| POST | /api/v1/passes/:passId/send-sms | API-Schlüssel (passes) | Sendet eine Einzelpass-SMS an die Empfänger-phoneNumber. |
| POST | /api/v1/email-campaigns | API-Schlüssel (delivery) | Erstellt einen Entwurf für eine Stapelversand-Kampagne. |
| POST | /api/v1/email-campaigns/estimate | API-Schlüssel (delivery) | Liefert Zielgruppengröße, zustellbare Pass-Anzahl und Guthabenbedarf. |
| POST | /api/v1/email-campaigns/:id/start | API-Schlüssel (delivery) | Reiht die Kampagne zur sofortigen Hintergrundausführung ein. |
| GET | /delivery/balance | API-Schlüssel (billing) | Gibt das aktuelle Prepaid-Nachrichtenguthaben und die Währung zurück. |
| POST | /delivery/top-up | API-Schlüssel (billing) | Erstellt eine Stripe-Checkout-Sitzung zum Kauf von Nachrichtenguthaben. |
| GET | /email-campaigns/track/:id/open | Öffentlich | Transparentes Trackingpixel zur Erfassung von E-Mail-Öffnungszeitstempeln. |
Weiterführende Dokumentation
-
Self-Service-Verteilung — PassFlows, Smart-Links, QR-Codes und NFC-Tags.
-
Download-Links & PassFlow — Smart-Link-Routing, PIN-Schutz und PassFlow-Lokalisierung.
-
Eigene Absenderadresse & benutzerdefiniertes SMTP — Vollständige Anleitung zur Einrichtung eigener SMTP-Relays.
-
Individuelles Branding & White-Label-Optionen — Eigene Domains und Portal-Theming.
