📧 Configuração Gmail SMTP para Envio de Emails¶

📋 Pré-requisitos¶

Conta Gmail ativa
Autenticação de 2 fatores habilitada no Google

🔐 Passo 1: Gerar Senha de App¶

1.1 Habilitar autenticação de 2 fatores (se ainda não tiver)¶

Acesse: https://myaccount.google.com/security
Em "Como fazer login no Google", clique em Verificação em duas etapas
Siga as instruções para ativar

1.2 Criar senha de app¶

Acesse: https://myaccount.google.com/apppasswords
Se solicitado, faça login novamente
Em "Selecionar app", escolha Mail (ou "Outro")
Em "Selecionar dispositivo", escolha Outro (nome personalizado)
Digite: iFriend Agents ou ifriend-platform
Clique em GERAR
IMPORTANTE: Copie a senha de 16 caracteres gerada (sem espaços)
Exemplo: abcd efgh ijkl mnop → usar como abcdefghijklmnop

🔧 Passo 2: Configurar Variáveis de Ambiente¶

Variáveis Necessárias¶

# Email do Gmail que enviará os emails
GMAIL_USER=contato@theifriend.com

# Senha de app de 16 caracteres (gerada no passo 1.2)
GMAIL_APP_PASSWORD=abcdefghijklmnop

# Nome que aparecerá como remetente (opcional)
GMAIL_FROM_NAME=iFriend

2.1 Desenvolvimento Local (.env)¶

Adicione ao arquivo .env na raiz do projeto:

# Gmail SMTP Configuration
GMAIL_USER=seu-email@gmail.com
GMAIL_APP_PASSWORD=sua-senha-de-app-16-chars
GMAIL_FROM_NAME=iFriend

2.2 Google Cloud (Cloud Build / Cloud Run)¶

Opção A: Via Console Web¶

Acesse: https://console.cloud.google.com/cloud-build/triggers
Selecione seu trigger (ex: slack-bot-deploy)
Clique em EDITAR
Role até Variáveis de substituição
Adicione as variáveis:

_GMAIL_USER = seu-email@gmail.com
_GMAIL_APP_PASSWORD = sua-senha-de-app-16-chars
_GMAIL_FROM_NAME = iFriend

Clique em SALVAR

Opção B: Via gcloud CLI¶

gcloud builds triggers update slack-bot-deploy \
  --substitutions=_GMAIL_USER="seu-email@gmail.com",_GMAIL_APP_PASSWORD="sua-senha-de-app",_GMAIL_FROM_NAME="iFriend"

Opção C: No cloudbuild.yaml¶

Certifique-se de que as variáveis sejam passadas para o Cloud Run:

- name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
  entrypoint: gcloud
  args:
    - 'run'
    - 'deploy'
    - 'slack-bot'
    - '--image=gcr.io/${PROJECT_ID}/slack-bot:${SHORT_SHA}'
    - '--region=us-central1'
    - '--set-env-vars'
    - >
      GMAIL_USER=${_GMAIL_USER},
      GMAIL_APP_PASSWORD=${_GMAIL_APP_PASSWORD},
      GMAIL_FROM_NAME=${_GMAIL_FROM_NAME}

2.3 Docker / docker-compose.yml¶

Adicione ao environment do serviço:

services:
  app:
    environment:
      - GMAIL_USER=${GMAIL_USER}
      - GMAIL_APP_PASSWORD=${GMAIL_APP_PASSWORD}
      - GMAIL_FROM_NAME=${GMAIL_FROM_NAME:-iFriend}

🧪 Passo 3: Testar a Configuração¶

3.1 Teste Manual (Python)¶

Crie um arquivo test_gmail.py:

import asyncio
import os
from dotenv import load_dotenv
from ifriend_agent.tools.enviar_email_gmail_tool import enviar_email_gmail_tool

load_dotenv()

async def test_email():
    result = await enviar_email_gmail_tool(
        destinatario_email="seu-email-teste@gmail.com",
        assunto="Teste Gmail SMTP - iFriend",
        corpo_mensagem="""
        <h1>Teste de Email</h1>
        <p>Se você recebeu este email, a configuração está funcionando! 🎉</p>
        <p>Data/Hora: 3 de janeiro de 2026</p>
        """
    )
    print(result)

asyncio.run(test_email())

Execute:

python test_gmail.py

3.2 Verificar Logs¶

Se der erro, verifique os logs:

# No Cloud Run
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=slack-bot" --limit 50

# Local
# Os logs aparecerão no terminal

⚙️ Uso na Aplicação¶

Importar e usar a tool¶

from ifriend_agent.tools.enviar_email_gmail_tool import enviar_email_gmail_tool

# Uso básico
result = await enviar_email_gmail_tool(
    destinatario_email="cliente@exemplo.com",
    assunto="Confirmação de Reserva #12345",
    corpo_mensagem="Olá! Sua reserva foi confirmada."
)

# Uso avançado com HTML
result = await enviar_email_gmail_tool(
    destinatario_email="cliente@exemplo.com",
    assunto="Orçamento Personalizado",
    corpo_mensagem="""
        <h1>Orçamento - Tour em Paris</h1>
        <p>Olá João,</p>

        <h2>Detalhes do Tour</h2>
        <table>
            <tr><th>Item</th><th>Valor</th></tr>
            <tr><td>Tour Privativo em Paris</td><td>R$ 2.500</td></tr>
            <tr><td>Guia em Português</td><td>Incluído</td></tr>
        </table>

        <p class="price">Total: R$ 2.500</p>

        <p>Atenciosamente,<br>Equipe iFriend</p>
    """
)

print(result)
# {'success': True, 'message': 'Email enviado...', 'smtp_response': '...'}

🔒 Segurança¶

✅ Boas Práticas¶

NUNCA comite senhas no Git
Use variáveis de ambiente
Use Google Secret Manager em produção (opcional)
Rotacione senhas de app periodicamente
Mantenha a senha de app separada da senha principal

🔐 Usar Google Secret Manager (Recomendado para Produção)¶

# 1. Criar secret
echo -n "sua-senha-de-app" | gcloud secrets create gmail-app-password --data-file=-

# 2. Dar permissão ao Cloud Run
gcloud secrets add-iam-policy-binding gmail-app-password \
  --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
  --role=roles/secretmanager.secretAccessor

# 3. No Cloud Run, use:
--set-secrets=GMAIL_APP_PASSWORD=gmail-app-password:latest

📊 Limites do Gmail SMTP¶

Limite	Valor
Emails por dia	500
Destinatários por email	100
Tamanho máximo do email	25 MB
Anexos	Suportados

💡 Se precisar de mais:¶

Use SendGrid (volta quando desbloquearem)
Use Amazon SES
Use Azure Communication Services
Configure um domínio personalizado com Google Workspace

🐛 Troubleshooting¶

Erro: "Username and Password not accepted"¶

Causa: Senha incorreta ou autenticação de 2 fatores não habilitada

Solução: 1. Verifique se a autenticação de 2 fatores está ativa 2. Gere uma nova senha de app 3. Copie sem espaços

Erro: "SMTP connection failed"¶

Causa: Firewall bloqueando porta 465

Solução: 1. Verifique se a porta 465 está aberta 2. Teste com telnet smtp.gmail.com 465

Erro: "Application-specific password required"¶

Causa: Tentando usar senha normal em vez de senha de app

Solução: - Gere uma senha de app específica (passo 1.2)

Emails vão para Spam¶

Solução: 1. Configure SPF, DKIM no seu domínio 2. Use um domínio verificado (ex: @theifriend.com em vez de @gmail.com) 3. Evite palavras spam no assunto

📚 Recursos Adicionais¶

🎯 Checklist de Configuração¶

[ ] Autenticação de 2 fatores habilitada
[ ] Senha de app gerada (16 caracteres)
[ ] Variáveis de ambiente configuradas (GMAIL_USER, GMAIL_APP_PASSWORD)
[ ] Teste local executado com sucesso
[ ] Variáveis configuradas no Google Cloud (se usar)
[ ] Email de teste recebido
[ ] Verificado que não foi para spam

Status: ✅ Pronto para uso Última atualização: 3 de janeiro de 2026