Skip to content
Help Center Guide · Pass Distribution
5 min readVerified 2026-11-16

Your Own Sender Address & Custom SMTP

Configure a custom SMTP relay server to send pass emails from your corporate domain with port flexibility, encrypted credential storage, and anti-SSRF security.

In This Guide

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:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
CUSTOM SMTP RELAY & CREDENTIAL ENCRYPTION
STAGE 01 PASSINSTANCE EMAIL DELIVERY DISPATCHER
Triggered via Pass Creation, Delivery Center Sendouts, or Download Page Email
STAGE 02 GATEWAY ROUTING & FEATURE GUARD
Checks workspace entitlement: AddonType.OWN_SMTP (€20/mo) or ownSmtp flag
Anti-SSRF Host Guard: validateSmtpHost validates destination IP address
STAGE 03 ENCRYPTED CREDENTIAL HYDRATION
Retrieves encrypted SMTP password from encrypted storage path: smtp/{customerId}
Decrypted in ephemeral memory; never logged or written to database plaintext
STAGE 04 CUSTOMER CORPORATE SMTP RELAY SERVER
Host: smtp.yourbrand.com | Ports: 587 (STARTTLS), 465 (SSL), or 2525
Dispatches message with customer's DKIM, SPF, and DMARC signatures
STAGE 05 RECIPIENT INBOX
Delivered from: passes@yourbrand.com (100% Branded Sender Identity)

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 flag ownSmtp).
  • 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:

PortProtocol / EncryptionSecurity RecommendationTypical Mail Providers
587STARTTLS (Explicit TLS)Recommended (Default): Connects in plaintext and upgrades immediately to TLS 1.3 before authenticating.Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark
465SMTPS (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
2525Alternative STARTTLSCloud-Friendly: Ideal for hosting on AWS, Azure, or Google Cloud where outbound port 25 is blocked or throttled.SendGrid, Mailgun, SparkPost
25Plaintext / Opportunistic TLSNot 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. 1
    Loopback Addresses: 127.0.0.1, localhost, ::1.
  2. 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)

  1. 3
    AWS Instance Metadata Service (IMDS): 169.254.169.254 and all 169.254.0.0/16 link-local ranges.
  2. 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": true with 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. 1
    Navigate to Settings -> Messaging -> Custom SMTP (/settings/workspace/messaging/smtp).
  2. 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).

  1. 3
    Click Send Test Email (POST /settings/smtp-config/test).
  2. 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.
  3. 5
    Once the test passes, click Save Configuration. All subsequent emails will now route through your server.

Custom SMTP REST API Endpoints

MethodEndpoint PathAuth ScopeDescription
GET/api/v1/settings/smtp-configAPI Key (settings)Fetches the current workspace SMTP configuration (password masked).
PUT/api/v1/settings/smtp-configAPI Key (settings)Updates SMTP connection parameters and encrypts password in encrypted storage.
POST/api/v1/settings/smtp-config/testAPI Key (settings)Performs live socket connection test and dispatches verification email.
DELETE/api/v1/settings/smtp-configAPI Key (settings)Deletes custom SMTP configuration and reverts workspace to managed email delivery.

Example: Testing SMTP Configuration Before Saving

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

JSON
{
  "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:

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

TEXT
v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@yourbrand.com; pct=100

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.