Skip to content
Hilfecenter-Anleitung · Pass-VerteilungOnboarding-Phase 5
8 Min. LesezeitGeprüft 2026-11-16

E-Mail- & SMS-Versand

Nutzen Sie Delivery Center Sendouts, E-Mail-Vorlagen, SES-Bounce-Überwachung und eigene SMTP-Absenderkonfiguration.

In dieser Anleitung

Prüfen Sie passende Dashboard-Bereiche, Steuerelemente und Zoom-Hinweise zu diesem Thema.

Vergrößerter UI-Fokus1 / 2
Wichtige UI-Elemente

Ausgabelimits & Zugriffskontrollen (Zoom)

Konfigurieren Sie unbegrenzte oder begrenzte Ausgabe, Zugangswege, Wallet-Routing sowie Schutzregeln wie „Erneuten Download nach Aktivierung blockieren“ und Empfänger-Deduplizierung.

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:

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
VERSANDPRÜFUNGEN & MEHRKANAL-VERSAND
STUFE 01 KAMPAGNENERSTELLUNG & VORABPRÜFUNG
1
Zielgruppenauswahl: Filter nach Vorlage, Status (ACTIVE) / onlyUninstalled
2
Laufzeitprüfungen für den Versand (sendout-runtime.gates.ts):
assertCustomerPaymentMethod: Gültige Zahlungsmethode oder Guthaben
isManualPassEmailActive: Versand-Schalter auf der Vorlage aktiviert
Platzhalterprüfung: Erzwingt Vorhandensein von {passDownloadUrl}
3
Reichweitenschätzung (POST/api/v1/email-campaigns/estimate)
STUFE 02 ASYNCHRONER VERSAND-WORKER & VORLAGEN-ENGINE
Lädt E-Mail-Vorlage & normalisiert Platzhalter automatisch: {{...}}{...}
Befüllt {passDownloadUrl}, {appleWalletUrl}, {googleWalletUrl}
Fügt HMAC-signierten {unsubscribeLink} & RFC-8058-Abmelde-Header ein
Erzwingt idempotencyKey-Deduplizierung pro Empfänger-Pass-Datensatz
STUFE 03A E-MAIL-ZUSTELL-GATEWAY
Verwaltete EU-E-Mail-Infrastruktur (eu-central-1 Frankfurt)
Oder verschlüsseltes eigenes SMTP
Tarif: 0,0005 € EUR pro E-Mail
STUFE 03B SMS-ZUSTELL-GATEWAY
Carrier-SMS-Zustellung mit E.164-Normalisierung
Alphanumerische Absenderkennung
Tarif: 0,03 € EUR pro SMS-Segment
STUFE 04 FEEDBACK-SCHLEIFE & SPERRLISTEN-WEBHOOKS
SES-SNS-Bounces & Beschwerden (/api/v1/webhooks/ses)Auto-Sperrliste
Echtzeit-Öffnungs-Trackingpixel (/email-campaigns/track/:id/open)
Zustellungsprotokolle & Aktivitätsstream (GET/delivery/history)

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-TokenTypTechnische Beschreibung & gerenderter Wert
{passDownloadUrl}ErforderlichDer 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}AliasUnterstützte Legacy-Aliase, die automatisch auf {passDownloadUrl} normalisiert werden.
{appleWalletUrl}Plattform-DirektlinkDirektlink zur Auslieferung des nativen Apple-Wallet-.pkpass-Pakets (application/vnd.apple.pkpass).
{googleWalletUrl}Plattform-DirektlinkDirekter Google-Wallet-Speicherlink (https://pay.google.com/gp/v/save/<jwt>).
{walletButtonText}Lokalisierter TextLokalisierte Schaltflächenbeschriftung (z. B. „Add to Wallet“, „Zu Apple Wallet hinzufügen“).
{firstName}, {lastName}, {name}KontaktName des Empfängers aus den Kundenattributen.
{passFlowLink}RegistrierungÖffentlicher Registrierungslink des zugehörigen PassFlows (/f/:url).
{unsubscribeLink}ComplianceHMAC-signierter Ein-Klick-Abmeldelink (GET /email/unsubscribe/:token).
{attributeName}Benutzerdefiniertes FeldJeder 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:

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

KanalPlattformtarifAbrechnungseinheitHinweise
E-Mail0,0005 € EURPro zugestellter E-MailInklusive SES-Routing, Bounce-Überwachung und Öffnungs-Tracking
SMS0,03 € EURPro GSM-7-Segment (160 Zeichen)Weltweites Mobilfunk-Carrier-Routing über Carrier-SMS-Zustellung
Push-Updates0,00 € (KOSTENLOS)Unbegrenzte PushsApple-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/balance ein.
  • 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. 1
    Navigieren Sie zu Pässe -> Einzelnen Pass erstellen.
  2. 2
    Geben Sie die Kundenattribute ein (firstName, email usw.).
  3. 3
    Aktivieren Sie im Ausgabedialog das Kontrollkästchen „Per E-Mail senden“.
  4. 4
    Klicken Sie auf Pass erstellen. Passinstance legt den Pass-Datensatz an, ruft umgehend POST /passes/:id/email/send auf 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.

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

MethodeEndpunkt-PfadAuth-ScopeBeschreibung
POST/api/v1/passes/:id/send-emailAPI-Schlüssel (passes)Sendet eine transaktionale Einzelpass-E-Mail mit der Standardvorlage.
POST/api/v1/passes/:passId/send-email-with-templateAPI-Schlüssel (passes)Sendet eine Einzelpass-E-Mail mit spezifischer templateId und idempotencyKey.
POST/api/v1/passes/:passId/send-smsAPI-Schlüssel (passes)Sendet eine Einzelpass-SMS an die Empfänger-phoneNumber.
POST/api/v1/email-campaignsAPI-Schlüssel (delivery)Erstellt einen Entwurf für eine Stapelversand-Kampagne.
POST/api/v1/email-campaigns/estimateAPI-Schlüssel (delivery)Liefert Zielgruppengröße, zustellbare Pass-Anzahl und Guthabenbedarf.
POST/api/v1/email-campaigns/:id/startAPI-Schlüssel (delivery)Reiht die Kampagne zur sofortigen Hintergrundausführung ein.
GET/delivery/balanceAPI-Schlüssel (billing)Gibt das aktuelle Prepaid-Nachrichtenguthaben und die Währung zurück.
POST/delivery/top-upAPI-Schlüssel (billing)Erstellt eine Stripe-Checkout-Sitzung zum Kauf von Nachrichtenguthaben.
GET/email-campaigns/track/:id/openÖffentlichTransparentes Trackingpixel zur Erfassung von E-Mail-Öffnungszeitstempeln.

Weiterführende Dokumentation

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.