Custom SMTP Relay Architecture
By default, Passinstance sends pass delivery notifications, welcome emails, and campaign sendouts through our optimized managed EU email infrastructure (eu-central-1 Frankfurt) email cluster. For organizations, financial institutions, and white-label agencies that require all outbound emails to originate strictly from their own corporate mail servers (such as Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, or an internal Postfix relay), Passinstance offers the Custom SMTP Relay feature.
When enabled, Passinstance routes all transactional pass dispatches and Delivery Center campaigns through your designated SMTP host, ensuring complete sender domain alignment, custom DKIM signing, and internal archiving compliance:
Pricing & Add-on Entitlement
The Custom SMTP Relay is a modular workspace capability:
-
Pricing: Available as a modular add-on at €20/month (
AddonType.OWN_SMTP, feature flagownSmtp). -
Included Volumes: When routing through your own SMTP server, you do not consume Passinstance platform email delivery fees; sending volume limits are governed exclusively by your own email provider's rate limits.
-
Activating the Add-on: Go to Settings -> Workspace -> Add-ons and toggle Custom SMTP Relay.
Supported Ports & Security Modes
The Passinstance SMTP client (request payload) supports standard and alternative SMTP submission ports:
| Port | Protocol / Encryption | Security Recommendation | Typical Mail Providers |
|---|---|---|---|
587 | STARTTLS (Explicit TLS) | Recommended (Default): Connects in plaintext and upgrades immediately to TLS 1.3 before authenticating. | Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark |
465 | SMTPS (Implicit SSL/TLS) | Secure: Connection is wrapped in TLS from the initial socket handshake (secure: true). | managed email delivery SMTP, private mail servers with dedicated SSL certificates |
2525 | Alternative STARTTLS | Cloud-Friendly: Ideal for hosting on AWS, Azure, or Google Cloud where outbound port 25 is blocked or throttled. | SendGrid, Mailgun, SparkPost |
25 | Plaintext / Opportunistic TLS | Not Recommended for Internet Delivery: Often blocked by ISPs and cloud firewalls to prevent spam. | Internal legacy mail relays within private enterprise perimeters |
Anti-SSRF Host Security Validation (validateSmtpHost)
To prevent Server-Side Request Forgery (SSRF) and protect cloud internal infrastructure, Passinstance validates every configured SMTP hostname against strict network boundaries (validateSmtpHost in smtp-config.service.ts):
Security Rule: Any attempt to configure an SMTP host that resolves to an internal, link-local, or private IP address throws an immediate
BadRequestException: Invalid SMTP host address.
The following destinations are permanently blocked:
-
1
Loopback Addresses:
127.0.0.1,localhost,::1. -
2
RFC 1918 Private IPv4 Ranges:
- 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.254and all169.254.0.0/16link-local ranges. -
4
Unresolvable Hostnames: Hostnames that fail public DNS A/AAAA record resolution are rejected.
Credential Storage in encrypted secret storage
Passinstance treats SMTP authentication credentials with zero-trust security:
-
encrypted storage Encryption: When you save your SMTP configuration, the password is encrypted and stored in encrypted secret storage under the tenant path
smtp/{customerId}. -
No Plaintext in database: The primary database stores only connection metadata (host, port, username, from-address, encryption mode). The password field in the database is null.
-
Redacted in API Responses: GET endpoints (
GET /settings/smtp-config) return"hasPassword": truewith the password masked as"********". Passwords are never sent back to the browser. -
Ephemeral Worker Access: When an outbound email is dispatched, the background job queue worker retrieves the secret directly from encrypted storage into temporary memory and disposes of it immediately after the socket session terminates.
Configuring Custom SMTP in Dashboard
-
1
Navigate to Settings -> Messaging -> Custom SMTP (
/settings/workspace/messaging/smtp). -
2
Fill in your server connection parameters:
- SMTP Host: FQDN of your mail server (e.g. smtp.sendgrid.net or smtp.office365.com). - Port: 587 (STARTTLS) or 465 (SSL). - Username: SMTP authentication username or API key. - Password: SMTP password or API token. - From Email Address: Sender address (e.g. passes@yourbrand.com). - From Sender Name: Display name (e.g. YourBrand Wallet Support).
-
3
Click Send Test Email (
POST /settings/smtp-config/test). -
4
Enter an email address you have access to and click Send. Passinstance tests the DNS resolution, TLS handshake, authentication, and delivers a sample test email.
-
5
Once the test passes, click Save Configuration. All subsequent emails will now route through your server.
Custom SMTP REST API Endpoints
| Method | Endpoint Path | Auth Scope | Description |
|---|---|---|---|
| GET | /api/v1/settings/smtp-config | API Key (settings) | Fetches the current workspace SMTP configuration (password masked). |
| PUT | /api/v1/settings/smtp-config | API Key (settings) | Updates SMTP connection parameters and encrypts password in encrypted storage. |
| POST | /api/v1/settings/smtp-config/test | API Key (settings) | Performs live socket connection test and dispatches verification email. |
| DELETE | /api/v1/settings/smtp-config | API Key (settings) | Deletes custom SMTP configuration and reverts workspace to managed email delivery. |
Example: Testing SMTP Configuration Before Saving
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"
}
Response (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 Authentication: SPF, DKIM & DMARC Alignment
To ensure high inbox delivery and prevent spam filtering when sending through your own SMTP server, ensure your domain DNS records are properly configured:
1. Sender Policy Framework (SPF)
Include your SMTP provider's SPF mechanism in your root domain's TXT record:
v=spf1 include:mailgun.org include:_spf.google.com ~all
2. DomainKeys Identified Mail (DKIM)
Ensure your mail provider has generated 2048-bit DKIM keys for your sending domain, and publish the corresponding public key CNAME records in your DNS.
3. DMARC Alignment
Publish a DMARC policy record (_dmarc.yourbrand.com) to enforce alignment between the RFC 5322 From: address and your verified SPF/DKIM identifiers:
v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@yourbrand.com; pct=100
Related Documentation
-
Email & SMS Delivery — Campaigns, templates, and sendout runtime gates.
-
Custom Branding & White-Label Options — Vanity download domains and portal themes.
-
Self-Service Distribution — PassFlows, smart links, and NFC distribution.
