Skip to content

📧 Configuração Gmail API com OAuth 2.0

📋 Visão Geral

Este guia explica como configurar o envio de emails usando Gmail API com OAuth 2.0, que é a solução recomendada para produção por ser mais robusta e segura que SMTP com senha de app.

✅ Vantagens do OAuth 2.0

  • ✅ Mais seguro (tokens revogáveis)
  • ✅ Sem limite rígido de 500 emails/dia
  • ✅ Melhor rastreabilidade e logs
  • ✅ Funciona melhor em ambientes de produção
  • ✅ Suporte a delegação de acesso

🚀 Passo 1: Criar Projeto no Google Cloud Console

1.1 Acessar Google Cloud Console

  1. Acesse: https://console.cloud.google.com/
  2. Faça login com sua conta Google
  3. Selecione ou crie um projeto
  4. Clique no seletor de projeto no topo
  5. Clique em "NOVO PROJETO"
  6. Nome: ifriend-gmail-api (ou similar)
  7. Clique em "CRIAR"

📬 Passo 2: Ativar Gmail API

2.1 Habilitar a API

  1. No console, vá para APIs & Services > Library
  2. Busque por "Gmail API"
  3. Clique em "Gmail API"
  4. Clique em ENABLE (ATIVAR)

🔐 Passo 3: Criar Credenciais OAuth 2.0

3.1 Configurar Tela de Consentimento

  1. Vá para APIs & Services > OAuth consent screen
  2. Escolha Externo (External) se não tiver Google Workspace
  3. Preencha as informações obrigatórias:
  4. App name: iFriend Agent
  5. User support email: seu-email@theifriend.com
  6. Developer contact: seu-email@theifriend.com
  7. Clique em SAVE AND CONTINUE
  8. Em "Scopes", clique em ADD OR REMOVE SCOPES
  9. Adicione o escopo: https://www.googleapis.com/auth/gmail.send
  10. Clique em UPDATE e depois SAVE AND CONTINUE
  11. Em "Test users", adicione o email que enviará os emails (ex: no-reply@theifriend.com)
  12. Clique em SAVE AND CONTINUE

3.2 Criar Credenciais

  1. Vá para APIs & Services > Credentials
  2. Clique em + CREATE CREDENTIALS > OAuth client ID
  3. Application type: Desktop app (mais fácil para obter refresh token)
  4. Name: iFriend Gmail OAuth
  5. Clique em CREATE
  6. IMPORTANTE: Copie e salve:
  7. Client ID (algo como: 123456-abc.apps.googleusercontent.com)
  8. Client Secret (algo como: GOCSPX-abc123...)

🎫 Passo 4: Obter Refresh Token

4.1 Instalar Google OAuth CLI (local)

pip install --upgrade google-auth-oauthlib google-auth-httplib2 google-api-python-client

4.2 Script para Gerar Refresh Token

Crie um arquivo get_gmail_refresh_token.py:

#!/usr/bin/env python3
"""
Script para obter refresh token do Gmail API.
"""
from google_auth_oauthlib.flow import InstalledAppFlow
import json

# Escopos necessários
SCOPES = ['https://www.googleapis.com/auth/gmail.send']

def main():
    """Executa fluxo OAuth para obter refresh token."""

    # Solicitar credenciais
    print("=" * 60)
    print("OBTER REFRESH TOKEN - GMAIL API")
    print("=" * 60)

    client_id = input("\nInforme o Client ID: ").strip()
    client_secret = input("Informe o Client Secret: ").strip()

    # Criar configuração do cliente
    client_config = {
        "installed": {
            "client_id": client_id,
            "client_secret": client_secret,
            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
            "token_uri": "https://oauth2.googleapis.com/token",
            "redirect_uris": ["http://localhost"],
        }
    }

    # Executar fluxo OAuth
    flow = InstalledAppFlow.from_client_config(
        client_config,
        scopes=SCOPES
    )

    print("\n🔓 Abrindo navegador para autorização...")
    print("   Faça login com a conta que enviará os emails")
    print("   (ex: no-reply@theifriend.com)\n")

    creds = flow.run_local_server(port=0)

    # Exibir tokens
    print("\n" + "=" * 60)
    print("✅ AUTORIZAÇÃO CONCLUÍDA!")
    print("=" * 60)

    print("\n📋 COPIE ESTAS INFORMAÇÕES:\n")
    print(f"GMAIL_USER={input('Digite o email usado na autorização: ')}")
    print(f"GOOGLE_CLIENT_ID={client_id}")
    print(f"GOOGLE_CLIENT_SECRET={client_secret}")
    print(f"GOOGLE_REFRESH_TOKEN={creds.refresh_token}")

    print("\n💡 Adicione estas variáveis ao .env ou Cloud Run")
    print("=" * 60)

if __name__ == "__main__":
    main()

4.3 Executar o Script

python get_gmail_refresh_token.py

O que acontecerá: 1. Você informará Client ID e Client Secret 2. Um navegador abrirá para você autorizar o app 3. Faça login com o email que enviará mensagens 4. Autorize o acesso ao Gmail 5. O script exibirá o REFRESH_TOKEN - COPIE E GUARDE COM SEGURANÇA!

⚙️ Passo 5: Configurar Variáveis de Ambiente

5.1 Desenvolvimento Local (.env)

Adicione ao arquivo .env:

# Gmail API OAuth 2.0
GMAIL_USER=no-reply@theifriend.com
GMAIL_FROM_NAME=Agente de IA iFriend
GOOGLE_CLIENT_ID=123456-abc.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-abc123def456
GOOGLE_REFRESH_TOKEN=1//0abc123def456ghi789jkl

5.2 Google Cloud (Cloud Build / Cloud Run)

Opção A: Via Console Web

  1. Acesse: https://console.cloud.google.com/cloud-build/triggers
  2. Edite seu trigger (ex: slack-bot-deploy)
  3. Em Variáveis de substituição, adicione:
_GMAIL_USER = no-reply@theifriend.com
_GMAIL_FROM_NAME = Agente de IA iFriend
_GOOGLE_CLIENT_ID = 123456-abc.apps.googleusercontent.com
_GOOGLE_CLIENT_SECRET = GOCSPX-abc123def456
_GOOGLE_REFRESH_TOKEN = 1//0abc123def456ghi789jkl

Opção B: Via cloudbuild.yaml

Já está configurado! Apenas substitua os placeholders:

substitutions:
  _GMAIL_USER: 'no-reply@theifriend.com'
  _GMAIL_FROM_NAME: 'Agente de IA iFriend'
  _GOOGLE_CLIENT_ID: 'SEU_CLIENT_ID_AQUI'
  _GOOGLE_CLIENT_SECRET: 'SEU_CLIENT_SECRET_AQUI'
  _GOOGLE_REFRESH_TOKEN: 'SEU_REFRESH_TOKEN_AQUI'

Opção C: Google Secret Manager (Recomendado para Produção)

# 1. Criar secrets
echo -n "SEU_CLIENT_SECRET" | gcloud secrets create gmail-client-secret --data-file=-
echo -n "SEU_REFRESH_TOKEN" | gcloud secrets create gmail-refresh-token --data-file=-

# 2. Dar permissão ao Cloud Run
PROJECT_NUMBER=$(gcloud projects describe ifriend-platform --format="value(projectNumber)")

gcloud secrets add-iam-policy-binding gmail-client-secret \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

gcloud secrets add-iam-policy-binding gmail-refresh-token \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

# 3. No Cloud Run deployment, usar:
--set-secrets=GOOGLE_CLIENT_SECRET=gmail-client-secret:latest,GOOGLE_REFRESH_TOKEN=gmail-refresh-token:latest

🧪 Passo 6: Testar a Configuração

6.1 Teste Local

python test_gmail_smtp.py

O script testará a conexão e enviará um email de teste.

6.2 Teste Manual

import asyncio
from ifriend_agent.tools.enviar_email_tool import enviar_email_tool

async def test():
    result = await enviar_email_tool(
        destinatario_email="seu-email@gmail.com",
        assunto="Teste Gmail OAuth 2.0",
        corpo_mensagem="<h1>Funcionou! 🎉</h1><p>OAuth configurado corretamente.</p>"
    )
    print(result)

asyncio.run(test())

🔒 Segurança

✅ Boas Práticas

  1. NUNCA comite tokens no Git
  2. Use Google Secret Manager em produção
  3. Rotacione tokens periodicamente
  4. Use contas de serviço dedicadas
  5. Monitore uso da API no Google Cloud Console
  6. Configure alertas de quota

🔄 Revogar Acesso

Se precisar revogar tokens:

  1. Acesse: https://myaccount.google.com/permissions
  2. Encontre "iFriend Agent"
  3. Clique em "Remover acesso"
  4. Gere novos tokens

📊 Limites e Quotas

Recurso Limite
Emails por dia (usuário Gmail gratuito) ~500*
Emails por dia (Google Workspace) 2.000-10.000*
Tamanho máximo do email 35 MB
Destinatários por email 100
Taxa de envio ~100/segundo

* Limites podem variar. Verifique: https://support.google.com/a/answer/166852

🐛 Troubleshooting

Erro: "invalid_grant"

Causa: Refresh token expirado ou inválido

Solução: 1. Gere um novo refresh token (Passo 4) 2. Atualize a variável GOOGLE_REFRESH_TOKEN

Erro: "insufficient authentication scopes"

Causa: Escopo gmail.send não autorizado

Solução: 1. Revogue acesso (ver seção Segurança) 2. Execute novamente o script do Passo 4 3. Autorize o escopo gmail.send

Erro: "Gmail API has not been used"

Causa: Gmail API não está ativada no projeto

Solução: 1. Vá para Google Cloud Console 2. APIs & Services > Library 3. Ative "Gmail API"

Emails vão para spam

Solução: 1. Configure SPF, DKIM e DMARC no domínio 2. Use um domínio verificado no Google Workspace 3. Evite palavras spam no assunto/corpo

📚 Recursos Adicionais

🎯 Checklist de Configuração

  • [ ] Projeto criado no Google Cloud Console
  • [ ] Gmail API ativada
  • [ ] Tela de consentimento OAuth configurada
  • [ ] Credenciais OAuth 2.0 criadas (Client ID + Secret)
  • [ ] Refresh token obtido via script
  • [ ] Variáveis de ambiente configuradas (local)
  • [ ] Variáveis configuradas no Google Cloud (se produção)
  • [ ] Teste executado com sucesso
  • [ ] Email de teste recebido
  • [ ] Tokens armazenados com segurança (Secret Manager)

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