Architektur des benutzerdefinierten SMTP-Relays
Standardmäßig versendet Passinstance Pass-Zustellbenachrichtigungen, Willkommens-E-Mails und Kampagnen über unseren optimierten E-Mail-Cluster der verwalteten EU-E-Mail-Infrastruktur (eu-central-1 Frankfurt). Für Unternehmen, Finanzinstitute und White-Label-Agenturen, bei denen sämtliche ausgehenden E-Mails strikt über die eigenen Firmen-Mailserver laufen müssen (wie Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark oder ein internes Postfix-Relay), bietet Passinstance die Funktion Benutzerdefinierter SMTP-Relay.
Nach Aktivierung leitet Passinstance alle transaktionalen Pass-Versendungen und Delivery-Center-Kampagnen über Ihren festgelegten SMTP-Host und gewährleistet damit vollständige Absenderdomain-Ausrichtung, eigene DKIM-Signierung sowie interne Archivierungs-Compliance:
Preise & Add-on-Berechtigung
Der benutzerdefinierte SMTP-Relay ist eine modulare Workspace-Funktion:
-
Preis: Verfügbar als modulares Add-on für 20 €/Monat (
AddonType.OWN_SMTP, Feature-FlagownSmtp). -
Enthaltene Volumina: Beim Versand über Ihren eigenen SMTP-Server fallen keine Passinstance-Plattformgebühren für den E-Mail-Versand an; die Versandlimits richten sich ausschließlich nach den Ratenbegrenzungen Ihres eigenen E-Mail-Anbieters.
-
Add-on aktivieren: Navigieren Sie zu Einstellungen -> Workspace -> Add-ons und aktivieren Sie Benutzerdefinierter SMTP-Relay.
Unterstützte Ports & Sicherheitsmodi
Der Passinstance-SMTP-Client (request payload) unterstützt standardmäßige und alternative SMTP-Einlieferungsports:
| Port | Protokoll / Verschlüsselung | Sicherheitsempfehlung | Typische E-Mail-Anbieter |
|---|---|---|---|
587 | STARTTLS (Explizites TLS) | Empfohlen (Standard): Verbindet unverschlüsselt und stuft vor der Authentifizierung sofort auf TLS 1.3 hoch. | Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark |
465 | SMTPS (Implizites SSL/TLS) | Sicher: Die Verbindung wird bereits ab dem ersten Socket-Handshake mit TLS geschützt (secure: true). | Verwalteter E-Mail-SMTP-Dienst, eigene Mailserver mit dedizierten SSL-Zertifikaten |
2525 | Alternatives STARTTLS | Cloud-freundlich: Ideal für Hosting auf AWS, Azure oder Google Cloud, wo ausgehender Port 25 blockiert oder gedrosselt ist. | SendGrid, Mailgun, SparkPost |
25 | Klartext / Opportunistisches TLS | Nicht für Internet-Zustellung empfohlen: Häufig von ISPs und Cloud-Firewalls zum Spamschutz blockiert. | Interne Legacy-Mail-Relays in geschlossenen Unternehmensnetzen |
Anti-SSRF-Host-Sicherheitsprüfung (validateSmtpHost)
Um Server-Side Request Forgery (SSRF) zu verhindern und interne Cloud-Infrastruktur zu schützen, validiert Passinstance jeden konfigurierten SMTP-Hostnamen anhand strenger Netzwerkgrenzen (validateSmtpHost in smtp-config.service.ts):
Sicherheitsregel: Jeder Versuch, einen SMTP-Host zu konfigurieren, der auf eine interne, Link-Local- oder private IP-Adresse aufgelöst wird, führt umgehend zu einer
BadRequestException: Invalid SMTP host address.
Folgende Ziele werden dauerhaft blockiert:
-
1
Loopback-Adressen:
127.0.0.1,localhost,::1. -
2
Private IPv4-Bereiche nach RFC 1918:
- 10.0.0.0/8 (10.0.0.0 - 10.255.255.255) - 172.16.0.0/12 (172.16.0.0 - 172.31.255.255) - 192.168.0.0/16 (192.168.0.0 - 192.168.255.255)
-
3
AWS Instance Metadata Service (IMDS):
169.254.169.254sowie sämtliche Link-Local-Bereiche169.254.0.0/16. -
4
Nicht auflösbare Hostnamen: Hostnamen ohne gültige öffentliche DNS-A-/AAAA-Auflösung werden abgewiesen.
Speicherung von Zugangsdaten im verschlüsselten Secret-Speicher
Passinstance behandelt SMTP-Authentifizierungsdaten nach Zero-Trust-Prinzipien:
-
Verschlüsselte Speicherung: Beim Speichern Ihrer SMTP-Konfiguration wird das Passwort verschlüsselt im verschlüsselten Secret-Speicher unter dem Mandantenpfad
smtp/{customerId}abgelegt. -
Kein Klartext in der Datenbank: Die Hauptdatenbank speichert ausschließlich Verbindungsmetadaten (Host, Port, Benutzername, Absenderadresse, Verschlüsselungsmodus). Das Passwortfeld in der Datenbank bleibt
null. -
Maskierung in API-Antworten: GET-Endpunkte (
GET /settings/smtp-config) liefern"hasPassword": trueund maskieren das Passwort als"********". Passwörter werden niemals an den Browser zurückübertragen. -
Flüchtiger Worker-Zugriff: Beim Versand einer ausgehenden E-Mail liest der Worker der Hintergrund-Job-Queue das Secret direkt aus dem verschlüsselten Speicher in den temporären Arbeitsspeicher ein und verwirft es unmittelbar nach Beendigung der Socket-Sitzung.
Benutzerdefiniertes SMTP im Dashboard konfigurieren
-
1
Navigieren Sie zu Einstellungen -> Nachrichten -> Benutzerdefiniertes SMTP (
/settings/workspace/messaging/smtp). -
2
Tragen Sie die Verbindungsparameter Ihres Servers ein:
- SMTP-Host: FQDN Ihres Mailservers (z. B. smtp.sendgrid.net oder smtp.office365.com). - Port: 587 (STARTTLS) oder 465 (SSL). - Benutzername: SMTP-Benutzername oder API-Schlüssel. - Passwort: SMTP-Passwort oder API-Token. - Absender-E-Mail-Adresse: Absenderadresse (z. B. passes@yourbrand.com). - Absendername: Anzeigename (z. B. YourBrand Wallet Support).
-
3
Klicken Sie auf Test-E-Mail senden (
POST /settings/smtp-config/test). -
4
Geben Sie eine E-Mail-Adresse ein, auf die Sie Zugriff haben, und klicken Sie auf Senden. Passinstance prüft DNS-Auflösung, TLS-Handshake und Authentifizierung und stellt eine Test-E-Mail zu.
-
5
Sobald der Test erfolgreich war, klicken Sie auf Konfiguration speichern. Alle künftigen E-Mails werden ab diesem Zeitpunkt über Ihren Server versendet.
REST-API-Endpunkte für benutzerdefiniertes SMTP
| Methode | Endpunkt-Pfad | Auth-Scope | Beschreibung |
|---|---|---|---|
| GET | /api/v1/settings/smtp-config | API-Schlüssel (settings) | Ruft die aktuelle Workspace-SMTP-Konfiguration ab (Passwort maskiert). |
| PUT | /api/v1/settings/smtp-config | API-Schlüssel (settings) | Aktualisiert die SMTP-Verbindungsparameter und speichert das Passwort im verschlüsselten Speicher. |
| POST | /api/v1/settings/smtp-config/test | API-Schlüssel (settings) | Führt einen Live-Socket-Verbindungstest durch und sendet eine Bestätigungs-E-Mail. |
| DELETE | /api/v1/settings/smtp-config | API-Schlüssel (settings) | Löscht die benutzerdefinierte SMTP-Konfiguration und stellt den Workspace wieder auf die verwaltete E-Mail-Zustellung um. |
Beispiel: SMTP-Konfiguration vor dem Speichern testen
POST /api/v1/settings/smtp-config/test HTTP/1.1
Host: api.passinstance.com
X-API-Key: <API_KEY>
Content-Type: application/json
{
"host": "smtp.mailgun.org",
"port": 587,
"user": "postmaster@mg.yourbrand.com",
"pass": "secret-api-key-99214",
"fromEmail": "passes@yourbrand.com",
"fromName": "YourBrand Wallet",
"secure": false,
"testRecipientEmail": "admin@yourbrand.com"
}
Antwort (200 OK):
{
"success": true,
"message": "SMTP test email sent successfully",
"details": {
"response": "250 2.0.0 Ok: queued as 7F8E9A10",
"accepted": ["admin@yourbrand.com"],
"rejected": []
}
}
Domain-Authentifizierung: SPF-, DKIM- & DMARC-Ausrichtung
Für eine hohe Posteingangs-Zustellrate und zur Vermeidung von Spam-Filtern beim Versand über Ihren eigenen SMTP-Server sollten Ihre DNS-Einträge sauber eingerichtet sein:
1. Sender Policy Framework (SPF)
Nehmen Sie den SPF-Mechanismus Ihres SMTP-Anbieters in den TXT-Eintrag Ihrer Hauptdomain auf:
v=spf1 include:mailgun.org include:_spf.google.com ~all
2. DomainKeys Identified Mail (DKIM)
Stellen Sie sicher, dass Ihr Mailanbieter 2048-Bit-DKIM-Schlüssel für Ihre Absenderdomain generiert hat, und veröffentlichen Sie die zugehörigen öffentlichen CNAME-Einträge in Ihrem DNS.
3. DMARC-Ausrichtung
Veröffentlichen Sie einen DMARC-Richtlinieneintrag (_dmarc.yourbrand.com), um die Ausrichtung zwischen der RFC-5322-From:-Adresse und Ihren verifizierten SPF-/DKIM-Kennungen durchzusetzen:
v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@yourbrand.com; pct=100
Weiterführende Dokumentation
-
E-Mail- & SMS-Zustellung — Kampagnen, Vorlagen und Versand-Laufzeitprüfungen.
-
Individuelles Branding & White-Label-Optionen — Eigene Download-Domains und Portal-Themes.
-
Self-Service-Verteilung — PassFlows, Smart-Links und NFC-Verteilung.
