Skip to content
Guia da Central de Ajuda · Distribuição de passes
6 min de leituraVerificado 2026-11-16

Seu próprio endereço de remetente e SMTP personalizado

Configure um servidor de retransmissão SMTP personalizado para enviar e-mails de passes do seu domínio corporativo com armazenamento criptografado de credenciais e segurança anti-SSRF.

Neste guia

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:

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
RELÉ SMTP PERSONALIZADO E ENCRIPTAÇÃO
ETAPA 01 DESPACHANTE DE ENTREGA DE E-MAIL PASSINSTANCE
Acionado por Criação de Passe, Envios do Centro de Entrega ou Página de Download
ETAPA 02 ENCAMINHAMENTO DE GATEWAY E VERIFICAÇÃO DE ACESSO
Verifica add-on do espaço: AddonType.OWN_SMTP (€20/mês) ou flag ownSmtp
Guarda Anti-SSRF: validateSmtpHost valida o endereço IP de destino
ETAPA 03 OBTENÇÃO DE CREDENCIAIS ENCRIPTADAS
Obtém palavra-passe SMTP encriptada do caminho seguro: smtp/{customerId}
Desencriptada em memória efémera; nunca registada em texto simples na BD
ETAPA 04 SERVIDOR DE RETRANSMISSÃO SMTP DO CLIENTE
Host: smtp.yourbrand.com | Portas: 587 (STARTTLS), 465 (SSL) ou 2525
Envia mensagem com assinaturas DKIM, SPF e DMARC do cliente
ETAPA 05 CAIXA DE ENTRADA DO DESTINATÁRIO
Entregue de: passes@yourbrand.com (Identidade de Remetente 100% da Marca)

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

PortaProtocolo / EncriptaçãoRecomendação de segurançaFornecedores de correio típicos
587STARTTLS (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
465SMTPS (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
2525STARTTLS AlternativoAdequado 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
25Texto simples / TLS OportunistaNã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. 1
    Endereços Loopback: 127.0.0.1, localhost, ::1.
  2. 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)

  1. 3
    AWS Instance Metadata Service (IMDS): 169.254.169.254 e todos os intervalos link-local 169.254.0.0/16.
  2. 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": true com 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. 1
    Aceda a Definições -> Mensagens -> SMTP Personalizado (/settings/workspace/messaging/smtp).
  2. 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).

  1. 3
    Clique em Enviar E-mail de Teste (POST /settings/smtp-config/test).
  2. 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.
  3. 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étodoCaminho do endpointEscopo de autenticaçãoDescrição
GET/api/v1/settings/smtp-configChave API (settings)Obtém a configuração SMTP atual do espaço de trabalho (palavra-passe mascarada).
PUT/api/v1/settings/smtp-configChave API (settings)Atualiza os parâmetros de ligação SMTP e encripta a palavra-passe no armazenamento encriptado.
POST/api/v1/settings/smtp-config/testChave 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-configChave 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

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

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

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:

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

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

Documentação relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.