Architettura del relay SMTP personalizzato
Per impostazione predefinita, Passinstance invia notifiche di consegna dei pass, e-mail di benvenuto e campagne dal nostro cluster ottimizzato di infrastruttura e-mail gestita nell'UE (eu-central-1 Francoforte). Per aziende, istituti finanziari e agenzie white-label che richiedono che tutte le e-mail in uscita provengano rigorosamente dai propri server di posta aziendali (come Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark o un relay Postfix interno), Passinstance offre la funzionalità Relay SMTP personalizzato.
Quando è abilitata, Passinstance instrada tutti gli invii transazionali di pass e le campagne del Delivery Center attraverso l'host SMTP designato, garantendo il pieno allineamento del dominio mittente, firma DKIM personalizzata e conformità per l'archiviazione interna:
Prezzi e abilitazione dell'add-on
Il Relay SMTP personalizzato è una funzionalità modulare del workspace:
-
Prezzo: disponibile come add-on modulare a €20/mese (
AddonType.OWN_SMTP, feature flagownSmtp). -
Volumi inclusi: instradando gli invii tramite il tuo server SMTP non consumi le tariffe di consegna e-mail della piattaforma Passinstance; i limiti di volume dipendono esclusivamente dai limiti di frequenza del tuo provider di posta.
-
Attivazione dell'add-on: vai su Impostazioni -> Workspace -> Add-on e attiva Relay SMTP personalizzato.
Porte supportate e modalità di sicurezza
Il client SMTP di Passinstance (request payload) supporta le porte di invio SMTP standard e alternative:
| Porta | Protocollo / Crittografia | Raccomandazione di sicurezza | Provider di posta tipici |
|---|---|---|---|
587 | STARTTLS (TLS esplicito) | Consigliata (Predefinita): si connette in chiaro ed esegue subito l'upgrade a TLS 1.3 prima dell'autenticazione. | Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark |
465 | SMTPS (SSL/TLS implicito) | Sicura: la connessione è protetta da TLS fin dall'handshake iniziale del socket (secure: true). | Consegna e-mail gestita SMTP, server di posta privati con certificati SSL dedicati |
2525 | STARTTLS alternativo | Ideale per il cloud: perfetta su hosting AWS, Azure o Google Cloud dove la porta 25 in uscita è bloccata o limitata. | SendGrid, Mailgun, SparkPost |
25 | Testo in chiaro / TLS opportunistico | Sconsigliata per consegna su Internet: spesso bloccata da ISP e firewall cloud per prevenire spam. | Relay di posta legacy interni entro perimetri aziendali privati |
Validazione di sicurezza anti-SSRF dell'host (validateSmtpHost)
Per prevenire attacchi Server-Side Request Forgery (SSRF) e proteggere l'infrastruttura cloud interna, Passinstance valida ogni hostname SMTP configurato rispetto a rigidi confini di rete (validateSmtpHost in smtp-config.service.ts):
Regola di sicurezza: Qualsiasi tentativo di configurare un host SMTP che risolva verso un indirizzo IP interno, link-local o privato genera immediatamente un'eccezione
BadRequestException: Invalid SMTP host address.
Le seguenti destinazioni sono bloccate in modo permanente:
-
1
Indirizzi di loopback:
127.0.0.1,localhost,::1. -
2
Intervalli IPv4 privati 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.254e tutti gli intervalli link-local169.254.0.0/16. -
4
Hostname non risolvibili: gli hostname che falliscono la risoluzione DNS pubblica dei record A/AAAA vengono respinti.
Archiviazione delle credenziali nello storage cifrato dei segreti
Passinstance tratta le credenziali di autenticazione SMTP con sicurezza zero-trust:
-
Crittografia nello storage cifrato: quando salvi la configurazione SMTP, la password viene crittografata e archiviata nell'archivio segreti crittografato sotto il percorso del tenant
smtp/{customerId}. -
Nessun testo in chiaro nel database: il database principale conserva solo i metadati di connessione (host, porta, nome utente, indirizzo mittente, modalità di crittografia). Il campo password nel database rimane nullo.
-
Oscuramento nelle risposte API: gli endpoint GET (
GET /settings/smtp-config) restituiscono"hasPassword": truecon la password mascherata come"********". Le password non vengono mai rinviate al browser. -
Accesso effimero dei worker: al momento dell'invio di un'e-mail in uscita, il worker della coda di job in background recupera il segreto direttamente dallo storage cifrato in memoria temporanea e lo elimina immediatamente al termine della sessione socket.
Configurare SMTP personalizzato nella Dashboard
-
1
Vai su Impostazioni -> Messaggistica -> SMTP personalizzato (
/settings/workspace/messaging/smtp). -
2
Compila i parametri di connessione del server:
- Host SMTP: FQDN del tuo server di posta (ad es. smtp.sendgrid.net o smtp.office365.com). - Porta: 587 (STARTTLS) o 465 (SSL). - Nome utente: nome utente di autenticazione SMTP o chiave API. - Password: password SMTP o token API. - Indirizzo e-mail mittente: indirizzo del mittente (ad es. passes@yourbrand.com). - Nome mittente: nome visualizzato (ad es. YourBrand Wallet Support).
-
3
Fai clic su Invia e-mail di test (
POST /settings/smtp-config/test). -
4
Inserisci un indirizzo e-mail a cui hai accesso e fai clic su Invia. Passinstance verifica la risoluzione DNS, l'handshake TLS, l'autenticazione e consegna un'e-mail di prova.
-
5
Una volta superato il test, fai clic su Salva configurazione. Tutte le e-mail successive verranno instradate attraverso il tuo server.
Endpoint REST API per SMTP personalizzato
| Metodo | Percorso endpoint | Ambito Auth | Descrizione |
|---|---|---|---|
| GET | /api/v1/settings/smtp-config | Chiave API (settings) | Recupera la configurazione SMTP corrente del workspace (password mascherata). |
| PUT | /api/v1/settings/smtp-config | Chiave API (settings) | Aggiorna i parametri di connessione SMTP e cifra la password nello storage crittografato. |
| POST | /api/v1/settings/smtp-config/test | Chiave API (settings) | Esegue un test di connessione socket dal vivo e invia un'e-mail di verifica. |
| DELETE | /api/v1/settings/smtp-config | Chiave API (settings) | Elimina la configurazione SMTP personalizzata e ripristina la consegna e-mail gestita sul workspace. |
Esempio: testare la configurazione SMTP prima del salvataggio
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"
}
Risposta (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": []
}
}
Autenticazione del dominio: allineamento SPF, DKIM e DMARC
Per assicurare un'elevata consegnabilità in posta in arrivo ed evitare i filtri antispam quando invii tramite il tuo server SMTP, verifica che i record DNS del dominio siano configurati correttamente:
1. Sender Policy Framework (SPF)
Includi il meccanismo SPF del tuo provider SMTP nel record TXT del dominio principale:
v=spf1 include:mailgun.org include:_spf.google.com ~all
2. DomainKeys Identified Mail (DKIM)
Verifica che il tuo provider di posta abbia generato chiavi DKIM a 2048 bit per il dominio di invio e pubblica i corrispondenti record CNAME della chiave pubblica nel tuo DNS.
3. Allineamento DMARC
Pubblica un record di policy DMARC (_dmarc.yourbrand.com) per applicare l'allineamento tra l'indirizzo From: RFC 5322 e i tuoi identificatori SPF/DKIM verificati:
v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@yourbrand.com; pct=100
Documentazione correlata
-
Consegna via e-mail e SMS — Campagne, modelli e controlli runtime di invio.
-
Branding personalizzato e opzioni white-label — Domini di download personalizzati e temi del portale.
-
Distribuzione self-service — PassFlow, smart link e distribuzione NFC.
