Configurar o e-mail SMTP do Google (Gmail/Workspace) para o Portal¶
Guia de administração (não é voltado ao cotista). O Portal do Cotista envia e-mails transacionais — link de ativação, redefinição de senha e notificações. Este guia mostra como configurar o envio via SMTP do Google (Gmail ou Google Workspace).
Nunca versione segredos
A senha do e-mail (App Password) e demais credenciais são segredos. Configure-os apenas por variáveis de ambiente / secrets do ambiente de execução do backend. Nunca os coloque em código, no repositório ou nesta documentação.
Pré-requisitos
- Uma conta Gmail ou Google Workspace que enviará os e-mails.
- Acesso administrativo ao ambiente do backend (
almare-nexus-backend) para definir variáveis/secrets. - Verificação em duas etapas (2FA) habilitada na conta Google (obrigatória para gerar uma App Password).
1. Escolher a conta remetente¶
Use uma conta dedicada (ex.: no-reply@seudominio.com no Workspace) em vez de uma conta pessoal.
No Workspace, o domínio já dá mais credibilidade e limites de envio maiores que o Gmail gratuito.
2. Gerar a App Password (senha de app)¶
O Google não aceita a senha normal da conta em clientes SMTP; é preciso uma App Password:
- Acesse myaccount.google.com → Segurança.
- Confirme que a Verificação em duas etapas está ativada.
- Abra Senhas de app (App passwords), crie uma nova (ex.: nome "Almare Nexus Portal").
- Copie a senha de 16 caracteres gerada. Ela será usada como a senha SMTP.
Alternativa no Workspace: SMTP relay
Para volumes maiores, o Google Workspace oferece o SMTP relay service
(smtp-relay.gmail.com), configurável no Admin Console (Apps → Google Workspace → Gmail →
Rotas). Ele permite limites bem superiores e autenticação por IP/domínio. Avalie-o se o volume
de e-mails ultrapassar os limites do envio autenticado por conta.
3. Definir as variáveis no backend¶
O backend lê a configuração de SMTP das variáveis abaixo (introduzidas no marco PORT-001). Sem
SMTP_HOST definido, o envio fica desativado (no-op) — útil em desenvolvimento/teste.
| Variável | Exemplo (Gmail/Workspace) | Descrição |
|---|---|---|
SMTP_HOST |
smtp.gmail.com |
Servidor SMTP do Google |
SMTP_PORT |
587 |
Porta (587 = STARTTLS) |
SMTP_USER |
no-reply@seudominio.com |
Conta remetente (login SMTP) |
SMTP_PASSWORD |
(App Password de 16 caracteres) | Segredo — nunca versionar |
SMTP_USE_TLS |
true |
Usa STARTTLS/TLS |
SMTP_FROM |
no-reply@seudominio.com |
Endereço "De" (padrão = SMTP_USER) |
SMTP_FROM_NAME |
Almare Nexus |
Nome exibido no remetente |
Nomes conforme o backend (a confirmar no deploy)
Os nomes acima refletem as configurações do backend em app/config/settings.py (PORT-001), sem
prefixo e sem diferenciar maiúsculas/minúsculas. Confirme com a equipe de infraestrutura o
mecanismo exato de injeção de secrets no seu ambiente (arquivo .env, secret manager etc.).
Parâmetros relacionados do portal (opcionais)¶
Controlam prazos de token e limite de reenvio de e-mails (têm padrões seguros; ajuste só se necessário):
| Variável | Padrão | Descrição |
|---|---|---|
PORTAL_ACTIVATION_TOKEN_TTL_HOURS |
48 |
Validade do link de ativação |
PORTAL_RESET_TOKEN_TTL_MINUTES |
60 |
Validade do link de redefinição de senha |
PORTAL_EMAIL_RESEND_MIN_INTERVAL_SECONDS |
60 |
Intervalo mínimo entre reenvios por e-mail |
PORTAL_EMAIL_RESEND_MAX_PER_HOUR |
5 |
Máximo de reenvios por hora por e-mail |
4. Reiniciar e testar¶
- Aplique as variáveis e reinicie o serviço do backend.
- Faça um teste ponta a ponta: solicite um primeiro acesso ou uma redefinição de senha com um e-mail real e confirme o recebimento.
- Verifique os logs do backend em caso de falha de autenticação ou de conexão.
Limites de envio do Gmail¶
Os limites do Google podem interromper o envio se ultrapassados. Valores de referência (podem mudar):
| Cenário | Limite aproximado por dia |
|---|---|
| Conta Gmail gratuita (SMTP autenticado) | ~500 e-mails |
| Conta Google Workspace (SMTP autenticado) | ~2.000 e-mails |
| SMTP relay do Workspace | Muito maior (uso corporativo) |
Planeje o volume
Se o volume de ativações + notificações se aproximar desses limites, migre para o SMTP relay do Workspace ou um serviço transacional dedicado. Ultrapassar o limite pode bloquear temporariamente o envio da conta.
Problemas comuns¶
Erro de autenticação (535 / Username and Password not accepted)
Use a App Password (não a senha da conta) e confirme que a 2FA está ativa. Verifique se
SMTP_USER corresponde exatamente à conta que gerou a App Password.
Conexão recusada ou timeout
Confirme SMTP_HOST=smtp.gmail.com, SMTP_PORT=587 e SMTP_USE_TLS=true. Verifique se a saída
para a porta 587 não está bloqueada por firewall.
E-mails param de sair de repente
Provável estouro do limite diário do Gmail. Aguarde a janela de 24h, reduza o volume ou migre para o SMTP relay/serviço transacional.
Em desenvolvimento não quero enviar e-mail real
Deixe SMTP_HOST sem valor: o envio vira no-op e nenhum e-mail real é disparado.