Skip to content

📧 Configuração MailerSend SMTP

Guia completo para configurar envio de emails via SMTP do MailerSend no projeto iFriend.

📋 Índice

  1. Visão Geral
  2. Pré-requisitos
  3. Configuração do MailerSend
  4. Configuração Local
  5. Configuração na Cloud
  6. Testes
  7. Troubleshooting

🎯 Visão Geral

O MailerSend é uma plataforma moderna de email com: - ✅ API REST e SMTP - ✅ Templates visuais - ✅ Analytics em tempo real - ✅ Webhooks para eventos - ✅ Suporte a múltiplos domínios - ✅ Plano gratuito generoso (3.000 emails/mês)

Quando usar MailerSend?

  • ✅ Precisa de analytics detalhados
  • ✅ Quer templates visuais
  • ✅ Necessita de SMTP confiável
  • ✅ Precisa de webhooks
  • ✅ Quer interface amigável

📦 Pré-requisitos

1. Conta MailerSend

  1. Acesse: https://www.mailersend.com/
  2. Crie uma conta gratuita
  3. Confirme seu email

2. Verificar Domínio

Importante: Você precisa verificar seu domínio antes de enviar emails.

  1. No dashboard, vá em Email → Domains
  2. Clique em Add Domain
  3. Digite seu domínio (ex: theifriend.com)
  4. Adicione os registros DNS fornecidos:
  5. TXT para verificação
  6. CNAME para DKIM
  7. MX (opcional, se quiser receber emails)
  8. Aguarde verificação (pode levar até 48h)

⚙️ Configuração do MailerSend

Passo 1: Obter Credenciais SMTP

  1. No dashboard, vá em Email → SMTP
  2. Você verá as informações:
SMTP Server: smtp.mailersend.net
Port: 587 (STARTTLS) ou 465 (SSL/TLS)
Username: MS_xxxxxx@trial-xxxxx.mlsender.net
Password: [Clique em "Show" para ver]
  1. Anote o username e password

Passo 2: Criar API Token (Alternativa)

Se preferir usar API token em vez de password:

  1. Vá em Settings → API Tokens
  2. Clique em Create Token
  3. Nome: iFriend SMTP
  4. Permissões: Selecione Email - Send
  5. Clique em Create
  6. Copie o token (não será mostrado novamente!)

🔧 Configuração Local

Arquivo .env

Adicione ao arquivo .env na raiz do projeto:

# MailerSend SMTP
MAILERSEND_SMTP_HOST=smtp.mailersend.net
MAILERSEND_SMTP_PORT=587
MAILERSEND_SMTP_USER=MS_xxxxxx@trial-xxxxx.mlsender.net
MAILERSEND_SMTP_PASSWORD=seu_password_ou_token_aqui
MAILERSEND_FROM_EMAIL=noreply@seudominio.com
MAILERSEND_FROM_NAME=iFriend

Valores Importantes

Variável Descrição Exemplo
MAILERSEND_SMTP_HOST Servidor SMTP smtp.mailersend.net
MAILERSEND_SMTP_PORT Porta SMTP 587 (STARTTLS) ou 465 (SSL)
MAILERSEND_SMTP_USER Username fornecido MS_xxxxxx@trial-xxxxx.mlsender.net
MAILERSEND_SMTP_PASSWORD Password ou API token String longa
MAILERSEND_FROM_EMAIL Email verificado noreply@seudominio.com
MAILERSEND_FROM_NAME Nome do remetente iFriend

⚠️ Importante: O email em MAILERSEND_FROM_EMAIL deve: - Pertencer a um domínio verificado - Estar no formato correto - Não pode ser email pessoal (Gmail, etc)

☁️ Configuração na Cloud

Google Cloud Build

Adicione as variáveis no cloudbuild.yaml:

substitutions:
  # ... outras variáveis

  # MailerSend SMTP
  _MAILERSEND_SMTP_HOST: smtp.mailersend.net
  _MAILERSEND_SMTP_PORT: '587'
  _MAILERSEND_SMTP_USER: ${_MAILERSEND_SMTP_USER}
  _MAILERSEND_SMTP_PASSWORD: ${_MAILERSEND_SMTP_PASSWORD}
  _MAILERSEND_FROM_EMAIL: noreply@theifriend.com
  _MAILERSEND_FROM_NAME: iFriend

Google Secret Manager

Para produção, armazene credenciais no Secret Manager:

# Criar secrets
echo -n "MS_xxxxxx@trial-xxxxx.mlsender.net" | \
  gcloud secrets create mailersend-smtp-user --data-file=-

echo -n "seu_password_ou_token" | \
  gcloud secrets create mailersend-smtp-password --data-file=-

# Dar acesso ao Cloud Build
gcloud secrets add-iam-policy-binding mailersend-smtp-user \
  --member=serviceAccount:PROJECT_NUMBER@cloudbuild.gserviceaccount.com \
  --role=roles/secretmanager.secretAccessor

gcloud secrets add-iam-policy-binding mailersend-smtp-password \
  --member=serviceAccount:PROJECT_NUMBER@cloudbuild.gserviceaccount.com \
  --role=roles/secretmanager.secretAccessor

Cloud Run

As variáveis de ambiente serão injetadas automaticamente:

- name: MAILERSEND_SMTP_HOST
  value: ${_MAILERSEND_SMTP_HOST}
- name: MAILERSEND_SMTP_PORT
  value: ${_MAILERSEND_SMTP_PORT}
- name: MAILERSEND_SMTP_USER
  valueFrom:
    secretKeyRef:
      name: mailersend-smtp-user
      key: latest
- name: MAILERSEND_SMTP_PASSWORD
  valueFrom:
    secretKeyRef:
      name: mailersend-smtp-password
      key: latest
- name: MAILERSEND_FROM_EMAIL
  value: ${_MAILERSEND_FROM_EMAIL}
- name: MAILERSEND_FROM_NAME
  value: ${_MAILERSEND_FROM_NAME}

🧪 Testes

Teste Local

Execute o script de teste:

python test_mailersend.py

Saída esperada:

✅ Arquivo .env carregado

🔍 Verificando configuração...
   MAILERSEND_SMTP_HOST: smtp.mailersend.net
   MAILERSEND_SMTP_PORT: 587
   MAILERSEND_SMTP_USER: ✅ Configurado
   MAILERSEND_SMTP_PASSWORD: ✅ Configurado
   MAILERSEND_FROM_EMAIL: noreply@theifriend.com
   MAILERSEND_FROM_NAME: iFriend

============================================================
📧 TESTE DE ENVIO DE EMAIL VIA MAILERSEND SMTP
============================================================

✉️  Email de teste será enviado PARA qual endereço?
   (Pressione ENTER para enviar para: noreply@theifriend.com)

   Email do destinatário: seu@email.com

📤 Enviando email para: seu@email.com
   Aguarde...

============================================================
📊 RESULTADO DO TESTE
============================================================

✅ EMAIL ENVIADO COM SUCESSO! 🎉

   Destinatário: seu@email.com
   Servidor: smtp.mailersend.net
   Porta: 587

💡 Verifique sua caixa de entrada (pode levar alguns segundos)
   Se não receber, verifique a pasta de SPAM

📊 Acompanhe estatísticas em: https://app.mailersend.com/

Verificar Analytics

  1. Acesse: https://app.mailersend.com/
  2. Vá em Email → Activity
  3. Veja estatísticas de:
  4. Emails enviados
  5. Entregas
  6. Aberturas
  7. Cliques
  8. Bounces

🔧 Troubleshooting

Erro: Authentication Failed

Erro de autenticação MailerSend: Verifique MAILERSEND_SMTP_USER e MAILERSEND_SMTP_PASSWORD

Soluções: 1. Verifique se copiou username/password corretos 2. Regenere o password no dashboard 3. Use API token em vez de password 4. Verifique se não tem espaços extras

Erro: Sender Not Verified

Sender address rejected: not owned by user

Soluções: 1. Verifique seu domínio no MailerSend 2. Use email que pertence ao domínio verificado 3. Aguarde conclusão da verificação DNS 4. Use o email de teste fornecido durante trial

Erro: Connection Timeout

Timeout ao conectar com smtp.mailersend.net

Soluções: 1. Verifique firewall/proxy 2. Teste porta 465 em vez de 587 3. Verifique conectividade de rede 4. Use VPN se estiver em rede restrita

Email vai para SPAM

Soluções: 1. Complete verificação SPF, DKIM e DMARC 2. Use domínio próprio verificado 3. Evite palavras "spam" no assunto 4. Configure warm-up (aumento gradual de envios) 5. Solicite whitelist no MailerSend

Limite de Envios

Plano Gratuito: - 3.000 emails/mês - 100 emails/dia para domínios não verificados

Soluções: 1. Verifique domínio para aumentar limites 2. Upgrade para plano pago 3. Use múltiplas contas (não recomendado)

📚 Recursos Úteis

🎯 Próximos Passos

  1. ✅ Verificar domínio no MailerSend
  2. ✅ Configurar variáveis de ambiente
  3. ✅ Executar teste local
  4. ✅ Configurar Secret Manager
  5. ✅ Deploy na Cloud
  6. ✅ Monitorar analytics
  7. ✅ Configurar webhooks (opcional)

Dúvidas? Consulte a documentação oficial ou abra uma issue.