Skip to content
Guida del Centro assistenza · Distribuzione pass
6 min di letturaVerificato 2026-11-16

Il tuo indirizzo mittente e SMTP personalizzato

Configura un server relay SMTP personalizzato per inviare e-mail di pass dal tuo dominio aziendale con archiviazione crittografata delle credenziali e sicurezza anti-SSRF.

In questa guida

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:

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
RELAY SMTP PERSONALIZZATO E CRITTOGRAFIA CREDENZIALI
FASE 01 DISPATCHER DI CONSEGNA E-MAIL PASSINSTANCE
Attivato da creazione pass, invii Delivery Center o e-mail da pagina di download
FASE 02 INSTRADAMENTO GATEWAY E CONTROLLO FUNZIONALITÀ
Verifica abilitazione workspace: AddonType.OWN_SMTP (€20/mese) o ownSmtp
Protezione host anti-SSRF: validateSmtpHost valida l'IP di destinazione
FASE 03 RECUPERO CREDENZIALI CRITTOGRAFATE
Recupera password SMTP cifrata da archivio cifrato: smtp/{customerId}
Decifrata in memoria effimera; mai registrata nei log né salvata in chiaro
FASE 04 SERVER RELAY SMTP AZIENDALE DEL CLIENTE
Host: smtp.yourbrand.com | Porte: 587 (STARTTLS), 465 (SSL) o 2525
Invia il messaggio con firme DKIM, SPF e DMARC del cliente
FASE 05 CASELLA DEL DESTINATARIO
Consegnata da: passes@yourbrand.com (Identità mittente 100% personalizzata)

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

PortaProtocollo / CrittografiaRaccomandazione di sicurezzaProvider di posta tipici
587STARTTLS (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
465SMTPS (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
2525STARTTLS alternativoIdeale per il cloud: perfetta su hosting AWS, Azure o Google Cloud dove la porta 25 in uscita è bloccata o limitata.SendGrid, Mailgun, SparkPost
25Testo in chiaro / TLS opportunisticoSconsigliata 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. 1
    Indirizzi di loopback: 127.0.0.1, localhost, ::1.
  2. 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)

  1. 3
    AWS Instance Metadata Service (IMDS): 169.254.169.254 e tutti gli intervalli link-local 169.254.0.0/16.
  2. 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": true con 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. 1
    Vai su Impostazioni -> Messaggistica -> SMTP personalizzato (/settings/workspace/messaging/smtp).
  2. 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).

  1. 3
    Fai clic su Invia e-mail di test (POST /settings/smtp-config/test).
  2. 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.
  3. 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

MetodoPercorso endpointAmbito AuthDescrizione
GET/api/v1/settings/smtp-configChiave API (settings)Recupera la configurazione SMTP corrente del workspace (password mascherata).
PUT/api/v1/settings/smtp-configChiave API (settings)Aggiorna i parametri di connessione SMTP e cifra la password nello storage crittografato.
POST/api/v1/settings/smtp-config/testChiave API (settings)Esegue un test di connessione socket dal vivo e invia un'e-mail di verifica.
DELETE/api/v1/settings/smtp-configChiave API (settings)Elimina la configurazione SMTP personalizzata e ripristina la consegna e-mail gestita sul workspace.

Esempio: testare la configurazione SMTP prima del salvataggio

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"
}

Risposta (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": []
  }
}

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:

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

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

Documentazione correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.