guia · gmail api

Como uma equipe de produto deve implementar a Gmail API com segurança?

Implemente a Gmail API como acesso delegado a uma caixa postal específica do Gmail, não como uma credencial genérica de entrega de e-mails. Escolha o menor escopo OAuth que atenda ao recurso, proteja o estado de autorização e os refresh tokens e mantenha cada caixa postal com escopo por tenant. Monte as mensagens com uma biblioteca madura de mensagens de internet, registre o ID de mensagem retornado pelo Gmail e sincronize as mudanças via Pub/Sub e registros de histórico. Trate a personificação por conta de serviço como uma decisão do administrador do Workspace. Por fim, mantenha a aceitação pela API, a entrega ao servidor receptor e a chegada à caixa de entrada como resultados separados.

Escolha o modelo de caixa postal antes de escrever código

A Gmail API opera sobre a caixa postal do Gmail de um usuário. Ela é adequada quando um produto precisa ler essa caixa postal, organizar seus marcadores e threads, criar rascunhos, enviar como o usuário autorizado ou sincronizar mudanças na caixa postal. Essa autoridade é materialmente mais ampla do que chamar uma API de e-mail da aplicação a partir de um domínio verificado do produto. Comece nomeando a função exata da caixa postal e o agente que concede o acesso. Um produto voltado ao usuário normalmente usa consentimento OAuth para cada conta Google conectada. Uma automação interna do Google Workspace pode, em vez disso, usar delegação em todo o domínio aprovada pelo administrador. Se o único requisito for enviar recibos, links de verificação, alertas ou outras mensagens disparadas pelo produto a partir de um domínio que a empresa controla, evite totalmente o acesso à caixa postal e avalie uma API de e-mail transacional. Essa decisão de arquitetura reduz acessos desnecessários antes que qualquer controle de segurança ou tela de consentimento precise compensá-los.

Autorize o escopo mais restrito possível

Configure um cliente OAuth para o tipo de aplicação correto, use uma URI de redirecionamento registrada exata e vincule a resposta de autorização à sessão do navegador que a iniciou com um valor de state imprevisível. Solicite o acesso no contexto, quando o usuário ativar o recurso que precisa dele. Para uma integração só de envio, `https://www.googleapis.com/auth/gmail.send` é mais restrito do que os escopos que leem ou modificam a caixa postal. O Google classifica `gmail.send` como sensível, enquanto escopos como `gmail.readonly`, `gmail.compose` e `gmail.modify` são restritos. Um app público que usa acesso sensível ou restrito pode exigir verificação OAuth, e o armazenamento ou a transmissão no servidor de dados de escopos restritos pode gerar requisitos adicionais de avaliação de segurança. Solicite acesso offline somente quando houver trabalho em segundo plano realmente necessário. Criptografe os refresh tokens, associe cada token a um único tenant interno e a um subject do Google, nunca o exponha ao código do navegador ou a logs e ofereça um caminho de desconexão testado que exclua as credenciais locais e interrompa o processamento em segundo plano.

Entenda as contas de serviço e a delegação em todo o domínio

Uma conta de serviço é uma identidade da aplicação, não uma caixa de entrada do Gmail pronta para uso. Sozinha, ela não ganha acesso às mensagens dos funcionários. Para dados de usuários do Google Workspace, um superadministrador precisa autorizar explicitamente o ID numérico do cliente da conta de serviço e uma lista exata de escopos OAuth por meio da delegação em todo o domínio. A aplicação então solicita credenciais delegadas para um usuário nomeado, e cada chamada de API age com as permissões desse usuário dentro dos escopos autorizados. Mantenha o subject personificado explícito nos dados do job e nos logs de auditoria, para que um worker em segundo plano não troque de caixa postal silenciosamente. Use contas de serviço separadas para cargas de trabalho materialmente diferentes, evite chaves privadas para download quando o runtime puder usar credenciais gerenciadas e revise as concessões em todo o domínio periodicamente. Contas pessoais do Gmail não têm um administrador do Workspace que possa conceder essa delegação em toda a organização; por isso, use o consentimento OAuth do usuário para essas contas.

Envie mensagens sem perder o controle nem a auditabilidade

O Gmail aceita uma mensagem de e-mail de internet completa no campo `raw`, codificada em base64url, por meio de `users.messages.send`; um produto também pode criar um rascunho e enviá-lo depois. Use uma biblioteca de mensagens mantida para gerar a estrutura de From, To, Cc, Bcc, Subject, Date, Message-ID, texto, HTML e anexos, em vez de juntar as linhas de cabeçalho manualmente. Valide destinatários e conteúdo antes da codificação, rejeite injeção de cabeçalhos e defina limites de tamanho explícitos. Torne a ação do produto idempotente antes de chamar o Gmail: persista uma chave estável do evento da aplicação, o subject da caixa postal pretendida e um estado da tentativa de envio. Após uma resposta bem-sucedida, armazene o ID de mensagem e o ID de thread retornados pelo Gmail junto com esse evento. Se o cliente atingir o timeout depois de transmitir a requisição, reconcilie o estado da caixa postal antes de tentar novamente, porque a mensagem pode já ter sido aceita. Uma nova tentativa às cegas pode gerar um e-mail duplicado mesmo quando a resposta original se perdeu. Use a criação de rascunhos com revisão humana quando o conteúdo ou os destinatários exigirem aprovação.

Sincronize as mudanças da caixa postal com registros de histórico

Em uma integração de caixa postal no servidor, um watch do Gmail publica sinais de mudança pelo Google Cloud Pub/Sub. A notificação é um aviso para sincronizar, não um payload de e-mail completo. Persista o history ID atual e a expiração da resposta do watch, confirme as notificações rapidamente e chame `users.history.list` a partir do último history ID confirmado com sucesso para descobrir mudanças em mensagens e marcadores. Busque apenas as mensagens de que o recurso precisa e avance o checkpoint depois que as gravações locais forem bem-sucedidas. As notificações podem atrasar ou chegar duplicadas; por isso, torne idempotente o processamento de mensagens e de histórico. O Gmail exige que o watch de uma caixa postal seja renovado pelo menos a cada sete dias e recomenda a renovação diária; agende a renovação bem antes da expiração e gere alertas em caso de falha. Se um history ID armazenado estiver fora do intervalo disponível no Gmail, a API retorna HTTP 404. Trate isso como um caminho de recuperação definido: faça uma sincronização completa controlada, estabeleça um novo checkpoint e retome o processamento incremental, em vez de tentar novamente o history ID inválido para sempre.

Use um fluxo de implementação e verificação em etapas

Primeiro, documente se o recurso envia, lê, modifica ou monitora e-mails e mapeie cada operação para o seu escopo OAuth mínimo. Segundo, crie projetos do Google Cloud ou clientes OAuth separados para desenvolvimento e produção, com URIs de redirecionamento exatas e responsáveis nomeados pelas credenciais. Terceiro, implemente a autorização com validação de state, acesso offline somente quando necessário, armazenamento criptografado de tokens, revogação de tokens e verificações de acesso no nível do tenant. Quarto, teste com caixas postais controladas: conecte, renove um access token expirado, revogue o consentimento, reconecte, envie uma vez, simule um timeout ambíguo e confirme a prevenção de duplicatas. Quinto, se for receber mudanças, provisione as permissões do Pub/Sub, inicie um watch, processe o histórico de forma incremental, force uma recuperação de checkpoint desatualizado e verifique a renovação do watch. Sexto, adicione filas de trabalho por usuário, backoff exponencial limitado, classificação estruturada de erros e logs de auditoria que, por padrão, omitam corpos de mensagem e tokens. Antes do lançamento, conclua qualquer verificação e revisão de segurança exigidas pelo Google, publique divulgações precisas sobre o uso de dados e ensaie a rotação de credenciais e a exclusão de dados de usuários.

Planeje cotas, novas tentativas e falhas parciais

O Gmail mede o uso da API em unidades de cota, não apenas pela contagem de requisições. A página de cotas do Google lista 1.200.000 unidades por minuto por projeto e 6.000 unidades por minuto por usuário por projeto. Ela lista `messages.send`, `drafts.send` e `watch` com 100 unidades cada, e um limite de 500 destinatários por mensagem. Os limites de envio separados do usuário do Gmail ainda se aplicam entre clientes de API, web e SMTP. Trate o console do Cloud e a documentação atual como entradas de configuração em tempo de execução em vez de codificar limites publicados na lógica de negócios. Serialize ou enfileire o trabalho de forma justa por caixa postal, limite a concorrência e tente novamente apenas respostas transitórias com backoff exponencial com jitter e um prazo finito. Não tente novamente erros de autorização, política, destinatário inválido ou mensagem malformada como se fossem problemas de capacidade. Um lote multipart reduz a sobrecarga de conexão, mas cada chamada interna ainda consome cota e pode falhar de forma independente.

Mantenha aceitação, entrega e chegada à caixa de entrada separadas

Uma chamada `messages.send` bem-sucedida significa que o Gmail aceitou a requisição de API autorizada e retornou um recurso Message do Gmail. Ela não prova que o servidor de e-mail de cada destinatário aceitou a mensagem e não consegue estabelecer como um sistema receptor classificou a mensagem. A entrega ao servidor do destinatário significa que o sistema de destino aceitou a responsabilidade SMTP. A chegada à caixa de entrada é um resultado de filtragem posterior, como caixa principal, promoções, quarentena ou spam. Portanto, a API de caixa postal do Gmail não substitui um fluxo de eventos do provedor quando um produto precisa de telemetria de entrega, bounce ou reclamação para e-mails transacionais. Guarde o ID de mensagem do Gmail para reconciliação, mas descreva o estado visível ao usuário com precisão, como enviado ou aceito pelo Gmail, a menos que evidências separadas comprovem a entrega. Autenticação, destinatários que esperam a mensagem, qualidade do conteúdo, comportamento de envio e política do destino afetam o tratamento posterior. Uma resposta de API não consegue determinar nem prometer a pasta final na caixa postal do destinatário.

Saiba quando uma API de e-mail transacional atende a uma função diferente

Use a API do Gmail quando o produto precisar de acesso autorizado à caixa postal do Gmail de uma pessoa ou organização, incluindo threads, marcadores, rascunhos ou sincronização de caixa postal. Uma API de e-mail transacional se encaixa em uma arquitetura diferente: mensagens acionadas pela aplicação enviadas de domínios que a organização controla, sem autoridade delegada para ler a caixa postal Gmail de um usuário. Um produto pode usar os dois tipos de sistema quando os limites são explícitos, por exemplo, OAuth do Gmail para ler a caixa postal conectada de um agente de suporte e um provedor transacional verificado separadamente para enviar recibos do produto. Mantenha credenciais, consentimento, armazenamentos de mensagens, políticas de novas tentativas e registros de auditoria separados para que a autoridade sobre a caixa postal não vaze para o envio em toda a aplicação e uma credencial transacional não possa ler o Gmail de um usuário.

Perguntas frequentes

Uma conta de serviço pode acessar qualquer caixa postal do Gmail?

Não. Uma conta de serviço não recebe automaticamente acesso aos dados de usuários do Gmail. Um superadministrador do Google Workspace precisa conceder delegação em todo o domínio ao ID numérico do cliente e aos escopos aprovados; depois disso, a aplicação personifica explicitamente um usuário dessa organização. Para contas pessoais do Gmail, use o consentimento OAuth do usuário.

Qual escopo OAuth uma integração do Gmail só de envio deve solicitar?

Comece avaliando `https://www.googleapis.com/auth/gmail.send`, que permite enviar em nome do usuário sem conceder leitura geral da caixa postal. Confirme que nenhum requisito do produto realmente precisa de rascunhos, leitura de mensagens, marcadores ou modificações antes de solicitar um escopo mais amplo, e leve em conta as regras de verificação do Google para escopos sensíveis.

Um envio bem-sucedido pela Gmail API significa que a mensagem foi entregue?

Não. Confirma que o Gmail aceitou a operação de API autorizada e retornou um registro de mensagem. A aceitação pelo servidor receptor e a chegada à caixa de entrada são estados posteriores separados. Não marque a mensagem como entregue nem prometa a chegada à caixa de entrada, a menos que outro sinal confiável sustente essa conclusão.

As notificações push do Gmail contêm a nova mensagem completa?

Não. Uma notificação do Pub/Sub sinaliza que o estado da caixa postal mudou e inclui informações usadas para continuar a sincronização. A aplicação deve consultar o histórico do Gmail a partir do history ID salvo, buscar os dados de mensagem necessários, processar de forma idempotente e então avançar o checkpoint.

Com que frequência o watch de uma caixa postal do Gmail precisa ser renovado?

O Google exige chamar `watch` pelo menos uma vez a cada sete dias e recomenda a renovação diária. Armazene a expiração retornada, renove antes dela, monitore falhas e mantenha um job de sincronização de fallback, para que uma renovação perdida não crie silenciosamente uma lacuna de dados sem limite.

Quando uma equipe deve usar uma API de e-mail transacional em vez da Gmail API?

Use uma API de e-mail transacional quando a função for enviar e-mails disparados pela aplicação a partir de domínios controlados pela organização e nenhum recurso precisar de acesso à caixa postal do Gmail de uma pessoa. Use a Gmail API quando o produto precisar especificamente de acesso delegado a mensagens, threads, marcadores, rascunhos, configurações ou autoridade de envio como (send-as) da caixa postal.

Fontes

Continue aprendendo

Guia de implementação de API de e-mail para equipes de produtoProjete uma integração segura com uma API de e-mail com domínios verificados, envios em fila, identificadores estáveis, novas tentativas controladas, eventos de entrega, supressão e isolamento entre tenants.