Arquitetura do servidor de retransmissão SMTP personalizado
Por predefinição, a Passinstance envia notificações de entrega de passes, e-mails de boas-vindas e campanhas de envio através do nosso cluster otimizado de infraestrutura europeia gerida de e-mail (eu-central-1 Frankfurt). Para organizações, instituições financeiras e agências white-label que exigem que todos os e-mails de saída tenham origem estritamente nos seus próprios servidores de correio empresariais (como Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark ou um servidor Postfix interno), a Passinstance disponibiliza a funcionalidade Servidor de Retransmissão SMTP Personalizado.
Quando ativada, a Passinstance encaminha todos os envios transacionais de passes e campanhas do Centro de Entrega através do seu servidor SMTP designado, garantindo alinhamento total do domínio remetente, assinatura DKIM própria e conformidade com o arquivo interno:
Preços e ativação do add-on
O Servidor de Retransmissão SMTP Personalizado é uma capacidade modular do espaço de trabalho:
-
Preço: Disponível como add-on modular por €20/mês (
AddonType.OWN_SMTP, feature flagownSmtp). -
Volumes Incluídos: Ao encaminhar através do seu próprio servidor SMTP, não consome taxas de entrega de e-mail da plataforma Passinstance; os limites de volume de envio são regidos exclusivamente pelos limites de taxa do seu próprio fornecedor de e-mail.
-
Ativar o Add-on: Aceda a Definições -> Espaço de Trabalho -> Add-ons e ative Servidor de Retransmissão SMTP Personalizado.
Portas suportadas e modos de segurança
O cliente SMTP da Passinstance (request payload) suporta portas de submissão SMTP padrão e alternativas:
| Porta | Protocolo / Encriptação | Recomendação de segurança | Fornecedores de correio típicos |
|---|---|---|---|
587 | STARTTLS (TLS Explícito) | Recomendado (Predefinido): Liga em texto simples e atualiza imediatamente para TLS 1.3 antes da autenticação. | Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark |
465 | SMTPS (SSL/TLS Implícito) | Seguro: A ligação é encapsulada em TLS desde o handshake inicial de socket (secure: true). | SMTP de entrega gerida de e-mail, servidores de correio privados com certificados SSL dedicados |
2525 | STARTTLS Alternativo | Adequado para Cloud: Ideal para alojamento na AWS, Azure ou Google Cloud onde a porta 25 de saída está bloqueada ou limitada. | SendGrid, Mailgun, SparkPost |
25 | Texto simples / TLS Oportunista | Não Recomendado para Entrega na Internet: Frequentemente bloqueada por ISPs e firewalls cloud para prevenir spam. | Servidores internos legados em perímetros empresariais privados |
Validação de segurança de host anti-SSRF (validateSmtpHost)
Para prevenir ataques Server-Side Request Forgery (SSRF) e proteger a infraestrutura interna na cloud, a Passinstance valida cada nome de host SMTP configurado face a fronteiras de rede rigorosas (validateSmtpHost em smtp-config.service.ts):
Regra de Segurança: Qualquer tentativa de configurar um host SMTP que resolva para um endereço IP interno, link-local ou privado gera imediatamente
BadRequestException: Invalid SMTP host address.
Os seguintes destinos estão permanentemente bloqueados:
-
1
Endereços Loopback:
127.0.0.1,localhost,::1. -
2
Intervalos IPv4 Privados 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 todos os intervalos link-local169.254.0.0/16. -
4
Nomes de Host Não Resolvíveis: Nomes de host que falhem a resolução DNS pública de registos A/AAAA são rejeitados.
Armazenamento de credenciais em cofre encriptado de segredos
A Passinstance trata as credenciais de autenticação SMTP com segurança zero-trust:
-
Encriptação em Armazenamento Seguro: Ao guardar a sua configuração SMTP, a palavra-passe é encriptada e armazenada em armazenamento encriptado de segredos sob o caminho do tenant
smtp/{customerId}. -
Sem Texto Simples na Base de Dados: A base de dados principal armazena apenas os metadados de ligação (host, porta, nome de utilizador, endereço de remetente, modo de encriptação). O campo da palavra-passe na base de dados é nulo.
-
Ocultação nas Respostas da API: Os endpoints GET (
GET /settings/smtp-config) devolvem"hasPassword": truecom a palavra-passe mascarada como"********". As palavras-passe nunca são enviadas de volta para o navegador. -
Acesso Efémero pelos Workers: Quando um e-mail de saída é enviado, o worker da fila de tarefas em segundo plano obtém o segredo diretamente do armazenamento encriptado para memória temporária e descarta-o imediatamente após o encerramento da sessão de socket.
Configurar SMTP personalizado no Painel
-
1
Aceda a Definições -> Mensagens -> SMTP Personalizado (
/settings/workspace/messaging/smtp). -
2
Preencha os parâmetros de ligação do seu servidor:
- Host SMTP: FQDN do seu servidor de correio (por exemplo, smtp.sendgrid.net ou smtp.office365.com). - Porta: 587 (STARTTLS) ou 465 (SSL). - Nome de Utilizador: Nome de utilizador de autenticação SMTP ou chave de API. - Palavra-passe: Palavra-passe SMTP ou token de API. - Endereço de E-mail do Remetente: Endereço remetente (por exemplo, passes@yourbrand.com). - Nome do Remetente: Nome de apresentação (por exemplo, Suporte Carteira YourBrand).
-
3
Clique em Enviar E-mail de Teste (
POST /settings/smtp-config/test). -
4
Introduza um endereço de e-mail ao qual tenha acesso e clique em Enviar. A Passinstance testa a resolução DNS, o handshake TLS, a autenticação e entrega um e-mail de teste de exemplo.
-
5
Assim que o teste for bem-sucedido, clique em Guardar Configuração. Todos os e-mails subsequentes passarão a ser encaminhados através do seu servidor.
Endpoints da API REST de SMTP personalizado
| Método | Caminho do endpoint | Escopo de autenticação | Descrição |
|---|---|---|---|
| GET | /api/v1/settings/smtp-config | Chave API (settings) | Obtém a configuração SMTP atual do espaço de trabalho (palavra-passe mascarada). |
| PUT | /api/v1/settings/smtp-config | Chave API (settings) | Atualiza os parâmetros de ligação SMTP e encripta a palavra-passe no armazenamento encriptado. |
| POST | /api/v1/settings/smtp-config/test | Chave API (settings) | Executa um teste de ligação de socket em direto e envia um e-mail de verificação. |
| DELETE | /api/v1/settings/smtp-config | Chave API (settings) | Elimina a configuração SMTP personalizada e reverte o espaço de trabalho para a entrega gerida de e-mail. |
Exemplo: Testar a configuração SMTP antes de guardar
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"
}
Resposta (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": []
}
}
Autenticação de domínio: Alinhamento SPF, DKIM e DMARC
Para garantir uma elevada taxa de entrega na caixa de entrada e evitar filtros de spam ao enviar através do seu próprio servidor SMTP, confirme que os registos DNS do seu domínio estão corretamente configurados:
1. Sender Policy Framework (SPF)
Inclua o mecanismo SPF do seu fornecedor SMTP no registo TXT do seu domínio raiz:
v=spf1 include:mailgun.org include:_spf.google.com ~all
2. DomainKeys Identified Mail (DKIM)
Certifique-se de que o seu fornecedor de correio gerou chaves DKIM de 2048 bits para o seu domínio remetente e publique os respetivos registos CNAME da chave pública no seu DNS.
3. Alinhamento DMARC
Publique um registo de política DMARC (_dmarc.yourbrand.com) para impor o alinhamento entre o endereço RFC 5322 From: e os seus identificadores SPF/DKIM verificados:
v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@yourbrand.com; pct=100
Documentação relacionada
-
Entrega por e-mail e SMS — Campanhas, modelos e portas de execução de envios.
-
Personalização de marca e opções White-Label — Domínios personalizados de transferência e temas do portal.
-
Distribuição em autoatendimento — PassFlows, ligações inteligentes e distribuição NFC.
