Explicação dos Escopos da API do Gmail: Escolha as Permissões Certas para Seu App

Unipile - Enviar E-mail via API em Python TOC
Unipile - Escopos da API do Gmail Herói
Guia da API do Gmail

Scopes da API do Gmail Explicados: Escolha o Permissões corretas para Seu App

Todos os escopos da API do Gmail documentados: de gmail.somente leitura para mail.google.com. Entenda os 3 níveis de sensibilidade, escolha o escopo mínimo que seu aplicativo realmente precisa e entregue seu fluxo OAuth mais rapidamente.

gmail-oauth-scopes.js
// Solicitando escopos da API do Gmail no fluxo OAuth const ESCOPOS = [ 'https://www.googleapis.com/auth/gmail.readonly', 'https://www.googleapis.com/auth/gmail.send', 'https://www.googleapis.com/auth/gmail.labels', ]; const authUrl = oauth2Cliente.gerarUrlDeAutenticação({ tipo_acesso: 'offline', escopo: ESCOPOS, prompt: 'consentimento', });
gmail.somente leitura Restrito
gmail.enviar Sensível
gmail.marcadores Não sensível
Fundamentos

O que são escopos da API do Gmail?

Antes de escrever a primeira linha de código OAuth, você precisa entender o que são os escopos da API do Gmail e por que escolher o escopo errado pode impedir que seu aplicativo vá para produção. Esta seção fornece o conhecimento fundamental em menos de dois minutos.

Definição

Escopos da API do Gmail são strings de permissão do OAuth 2.0 que definem exatamente quais recursos do Gmail seu aplicativo pode acessar em nome de um usuário. Quando um usuário autoriza seu aplicativo, o Google apresenta uma tela de consentimento listando os escopos da API do Gmail que seu aplicativo solicitou. O usuário concede ou nega o acesso com base nesses escopos. Uma vez concedido, seu token de acesso é limitado exatamente às ações que esses escopos permitem - nada mais.

Limite de segurança

Os escopos da API do Gmail criam um limite rígido em torno do que seu token pode fazer. Mesmo que seu servidor seja comprometido, um invasor com um gmail.somente leitura O token não pode enviar ou excluir e-mails. Os escopos são aplicados no lado do servidor pelo Google.

Portal de verificação do Google

Escopos restritos da API do Gmail exigem que seu aplicativo passe pela avaliação de segurança do Google antes que você possa usá-los em produção com mais de 100 usuários de teste. A escolha incorreta do escopo pode adicionar semanas ou meses ao seu cronograma de lançamento.

Sinal de confiança do usuário

Solicitar mais permissões da API do Gmail do que seu aplicativo precisa aciona um aviso de "Este aplicativo deseja acesso amplo à sua Conta do Google". Escopos mínimos da API do Gmail produzem uma tela de consentimento mais simples, aumentando a conversão e a confiança do usuário.

Ignorar o gerenciamento de escopo completamente. O Unipile lida com o OAuth e os escopos do Gmail internamente - sua equipe se concentra na lógica do produto, não em strings de permissão.

Construa com Unipile
Unipile - Níveis de Sensibilidade do Escopo do Gmail
Classificação de Escopo

Os 3 Níveis de Sensibilidade Explicados

O Google classifica todos os escopos da API do Gmail em 3 níveis de sensibilidade. Cada nível determina os requisitos de verificação antes que seu aplicativo possa ser publicado. Compreender essa classificação é a decisão mais importante que você toma ao planejar sua integração do Gmail.

Não sensível
Escopos não sensíveis

O nível de risco mais baixo. Esses escopos acessam dados limitados e não pessoais do Gmail. O Google não exige uma avaliação formal de segurança para usá-los em produção.

Verificação Revisão padrão do aplicativo OAuth
Usuários de teste Ilimitado após a verificação do aplicativo
Exemplos
gmail.marcadores gmail.addons.current.action.compose
Sensível
Escopos Sensíveis

Nível de risco médio. Esses escopos acessam dados de mensagens do Gmail que podem expor informações pessoais. Verificação adicional é necessária antes do uso em produção.

Verificação Verificação de aplicativo OAuth do Google necessária
Usuários de teste Até 100 em fase de testes
Exemplos
gmail.enviar gmail.addons.current.message.readonly
Restrito
Escopos Restritos

Nível de risco mais elevado. Esses escopos concedem acesso amplo ou sensível aos dados do Gmail. O Google exige uma avaliação formal de segurança por um auditor terceirizado aprovado.

Verificação Avaliação anual de segurança (~1.000–4.000/ano)
Usuários de teste Até 100 em fase de testes
Exemplos
gmail.somente leitura gmail.modificar mail.google.com/
Critérios Não sensível Sensível Restrito
Acessa o corpo da mensagem Não Às vezes Sim
Avaliação de segurança necessária Não Não Sim
Avaliação do aplicativo necessária Sim Sim Sim
Recertificação anual Não Não Sim
Nível de aviso da tela de consentimento Padrão Padrão + divulgação Aviso de acesso amplo
Custo típico para verificar Grátis Grátis ~$500/ano (avaliador)
Acessa o corpo da mensagem
Não sensívelNão
SensívelÀs vezes
RestritoSim
Avaliação de segurança necessária
Não sensívelNão
SensívelNão
RestritoSim
Avaliação do aplicativo necessária
Não sensívelSim
SensívelSim
RestritoSim
Recertificação anual
Não sensívelNão
SensívelNão
RestritoSim
Nível de aviso da tela de consentimento
Não sensívelPadrão
SensívelPadrão + divulgação
RestritoAviso de acesso amplo
Custo típico para verificar
Não sensívelGrátis
SensívelGrátis
Restrito~$500/ano (avaliador)
Referência Completa

Referência Completa de Escopo da API do Gmail

A lista completa de escopos da API do Gmail, agrupada por nível de sensibilidade. Use esta tabela como sua única referência ao escolher permissões da API do Gmail para seu aplicativo. Escopos marcados como "2026" refletem as adições mais recentes à lista de escopos do Google.

URI de Escopo Nível de acesso O que Acessa Quando Usar
gmail.addons.current.action.compose Não sensível Permite que complementos componham e enviem e-mails durante uma ação de composição Complementos do Gmail que redigem ou enviam e-mails em nome do usuário dentro da janela de composição
gmail.addons.current.message.action Não sensível Permite que add-ons visualizem o e-mail atual durante uma ação de mensagem Complementos do Gmail que reagem a uma ação de e-mail (arquivamento, rotulagem) no contexto da mensagem
gmail.marcadores 2026 Não sensível Ver e editar rótulos (criar, renomear, excluir), mas não o conteúdo da mensagem Aplicativos que organizam e-mails com etiquetas sem precisar ler o corpo das mensagens
URI de Escopo Nível de acesso O que Acessa Quando Usar
gmail.addons.current.message.metadata Sensível Cabeçalhos e metadados de e-mail (De, Para, Assunto, Data) no contexto de um complemento - não o corpo da mensagem Complementos que exibem informações contextuais com base no remetente ou assunto sem ler o corpo
gmail.addons.current.message.readonly Sensível Acesso total de leitura ao e-mail atual, incluindo corpo e anexos, no contexto do complemento Complementos que analisam ou extraem dados da mensagem aberta.
gmail.enviar Sensível Enviar e-mail em nome do usuário autenticado - sem acesso de leitura ou modificação Aplicativos que enviam apenas e-mails transacionais ou de prospecção e não precisam ler a caixa de entrada
URI de Escopo Nível de acesso O que Acessa Quando Usar
mail.google.com/ Restrito Acesso completo à caixa de correio: ler, redigir, enviar e excluir permanentemente e-mails e configurações Somente quando você precisar de todas as capacidades do Gmail em um único escopo - tipicamente integrações legadas
gmail.somente leitura Restrito Acesso somente leitura a todas as mensagens, threads, marcadores e configurações - não pode enviar ou modificar Ferramentas de análise, arquivamento, pesquisa ou inteligência de e-mail que apenas leem dados da caixa de entrada
gmail.escrever Restrito Crie e gerencie rascunhos e envie esses rascunhos - sem acesso a emails existentes Ferramentas de gerenciamento de rascunhos, redatores de e-mail ou aplicativos que enfileiram e-mails antes de enviá-los
gmail.inserir 2026 Restrito Inserir mensagens na caixa de entrada do Gmail apenas - não pode ler ou enviar e-mails existentes Ferramentas ou sistemas de migração que importam e-mails para o Gmail de fontes externas
gmail.modificar Restrito Ler, compor, enviar e gerenciar e-mails e rótulos - não é possível excluir permanentemente Clientes de e-mail completos, ferramentas de sincronização de CRM, integrações de helpdesk que precisam ler+enviar+rotular
metadados do gmail Restrito Apenas cabeçalhos e rótulos - sem acesso ao corpo ou anexos do e-mail Aplicativos que categorizam ou roteiam e-mails com base em metadados sem ler conteúdo privado
gmail.configurações.básico Restrito Gerenciar configurações básicas do Gmail: filtros, regras de encaminhamento, configurações de POP/IMAP Ferramentas de produtividade de e-mail que configuram roteamento ou filtragem do Gmail em nome dos usuários
gmail.configurações.compartilhamento Restrito Gerenciamento de configurações sensíveis: aliases de envio como, delegados, respostas automáticas de férias (somente administrador do domínio) Ferramentas apenas para administradores do Workspace - requer privilégios de administrador de domínio para ativar

Não gerencie esses escopos da API do Gmail manualmente. A integração do Gmail da Unipile gerencia solicitações de escopo OAuth, atualização de tokens e fluxos de reautorização automaticamente em todas as contas vinculadas de seus usuários.

Crie seu aplicativo Gmail
Matriz de Casos de Uso

Qual escopo da API do Gmail você precisa?

O princípio mais importante na seleção de escopos da API do Gmail é o princípio de acesso mínimo: solicite apenas as permissões da API do Gmail que seu aplicativo realmente precisa. Esta tabela mapeia casos de uso comuns para o escopo mínimo recomendado, ajudando você a evitar sobrecarga de verificação desnecessária e a proteger a confiança do usuário.

Caso de uso Escopo Mínimo Nível de Verificação Anotações
Enviar e-mails apenas (sem ler a caixa de entrada) gmail.enviar Sensível Ideal para ferramentas transacionais ou de prospecção. Sem acesso a mensagens existentes.
Leia a caixa de entrada para análises ou pesquise gmail.somente leitura Restrito Acesso completo de leitura a todas as mensagens e configurações. Requer avaliação de segurança anual.
Cliente de e-mail completo (ler + enviar + etiquetar) gmail.modificar Restrito Preferido sobre mail.google.com/ como exclui a exclusão permanente. Cobre a maioria dos casos de uso de CRM e helpdesk.
Arquivar ou fazer backup de e-mails de forma permanente mail.google.com/ Restrito Use apenas quando realmente precisar do acesso para exclusão. Isso aciona o aviso de consentimento mais abrangente do Google.
Organizar apenas etiquetas gmail.marcadores Não sensível Novidade em 2026. Permissões mínimas para gerenciamento de rótulos sem leitura de mensagens.
Gerenciamento de rascunhos (fila antes do envio) gmail.escrever Restrito Acesso a rascunhos e capacidade de envio, mas sem acesso de leitura a mensagens existentes.
Roteamento ou categorização de metadados metadados do gmail Restrito Apenas cabeçalhos e rótulos - sem acesso ao corpo da mensagem. Bom para motores de roteamento que respeitam a privacidade da mensagem.
Migração/importação de e-mail para o Gmail gmail.inserir Restrito Novidade em 2026. Acesso somente para inserção — uma alternativa com escopo mais restrito a mail.google.com/ para importar ferramentas.
Configurar filtros e encaminhamento do Gmail gmail.configurações.básico Restrito Gerenciar filtros, rótulos e regras de encaminhamento. Sem acesso ao corpo da mensagem.
Complemento do Gmail: exibir contexto do remetente gmail.addons.current.message.metadata Sensível Cabeçalhos apenas no contexto do complemento. Evita acesso completo à leitura da mensagem.
Combine escopos apenas quando necessário

Você pode combinar vários escopos da API do Gmail em uma única solicitação OAuth (por exemplo, gmail.enviar + gmail.marcadores), mas cada escopo adiciona à divulgação na tela de consentimento. Sempre audite sua lista de escopos antes de ir para produção. Se você estiver construindo um produto de sincronização completo do Gmail, o Guia da API de E-mail OAuth cobre o fluxo completo, incluindo gerenciamento de tokens e reautorização de escopo.

Processo de Verificação

Verificação de Escopo Restrito: O que significa para seu aplicativo

Se o seu aplicativo precisar de qualquer escopo restrito da API do Gmail, incluindo gmail.somente leitura, gmail.modificarou mail.google.com/ - você deve completar o processo de avaliação de segurança do Google antes de publicar com mais de 100 usuários de teste. Veja como é esse processo e como minimizar a sobrecarga.

1
Registre seu aplicativo OAuth no Google Cloud Console

Crie um projeto, ative a API do Gmail e configure a tela de consentimento do OAuth. Preencha todos os campos obrigatórios: nome do aplicativo, e-mail de suporte, domínios autorizados e URL da política de privacidade. Esta etapa é necessária para qualquer nível de escopo da API do Gmail.

2
Enviar para revisão do aplicativo com escopos restritos declarados

Na tela de consentimento do OAuth, clique em "Preparar para verificação". Declare cada escopo restrito da API do Gmail e forneça uma justificativa explicando por que seu aplicativo precisa dele. A equipe do Google revisa isso antes de encaminhá-lo para um avaliador de segurança.

3
Concluir a avaliação de segurança de terceiros

O Google encaminha aplicativos de escopo restrito a um avaliador aprovado (Leviathan Security, Coalfire, etc.). A avaliação custa aproximadamente 1.450 dólares por ano. É necessário fornecer uma demonstração, explicar as práticas de tratamento de dados e passar por uma análise técnica da sua implementação do OAuth.

4
Recertificação anual para acesso contínuo

Escopos restritos da API do Gmail exigem recertificação anual. Se você perder a janela de renovação, o Google poderá revogar o acesso de produção do seu aplicativo. Planeje este custo recorrente e ciclo de conformidade desde o primeiro dia da arquitetura da sua integração com o Gmail.

Como evitar ou minimizar a verificação de escopo restrito

Escolher gmail.enviar sobre gmail.modificar quando seu aplicativo envia apenas e-mails e não precisa ler a caixa de entrada. gmail.enviar é um escopo sensível (não restrito) e pula completamente a avaliação de segurança.

Uso metadados do gmail em vez de gmail.somente leitura se seu aplicativo roteia ou categoriza e-mails sem ler o conteúdo do corpo. Você ainda precisa de verificação, mas o escopo é mais restrito e mais fácil de justificar para o Google.

Use uma plataforma que já tenha verificação do Google. Quando você constrói sobre Integração do Gmail da Unipile, seu aplicativo se beneficia das credenciais OAuth pré-verificadas da Unipile, portanto, você não precisa passar pela avaliação de escopo restrito. Este é o caminho mais rápido para a produção para a maioria dos produtos SaaS.

Permaneça na janela de teste de 100 usuários durante o desenvolvimento inicial. Você pode testar escopos restritos da API do Gmail com até 100 contas do Google sem concluir a verificação completa. Adicione contas de teste nas configurações da tela de consentimento do OAuth no Google Cloud Console.

Pule completamente o processo de verificação do Google. O OAuth hospedado do Gmail da Unipile já é verificado para escopos restritos da API do Gmail - suas contas vinculadas se conectam imediatamente sem avaliações adicionais.

Comece a construir hoje
Implementação

Como solicitar escopos da API do Gmail em seu fluxo OAuth

Depois de saber quais escopos da API do Gmail seu aplicativo precisa, você os declara ao gerar o URL de autorização. Aqui estão exemplos de código funcionais em Node.js e Python mostrando exatamente como passar permissões da API do Gmail para a tela de consentimento do OAuth.

gmail-scopes-node.js
// Node.js — Escopos da API do Gmail no fluxo OAuth // Usa google-auth-library (cliente oficial do Google) const { OAuth2Client } = require('biblioteca-de-autenticação-google'); const oauth2Client = new OAuth2Client( process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, process.env.REDIRECT_URI ); // Defina os escopos da API do Gmail que seu aplicativo precisa // Princípio: solicite o escopo mínimo necessário const ESCOPOS = [ 'https://www.googleapis.com/auth/gmail.readonly', // restrito 'https://www.googleapis.com/auth/gmail.send', // sensível 'https://www.googleapis.com/auth/gmail.labels', // não sensível ]; // Gere a URL de autorização OAuth const authUrl = oauth2Cliente.gerarUrlDeAutenticação({ tipo_acesso: 'offline', // solicita novo token de acesso escopos: ESCOPOS, prompt: 'consentimento', // forçar consentimento para obter token de atualização }); console.log('Redirecionar usuário para:', _authUrl); // Após o usuário autorizar, troca o código por tokens async function obterTokens(código) { const { tokens } = await oauth2Cliente.obterToken(código); oauth2Cliente.definirCredenciais(tokens); return tokens; }
URL de autorização gerada - escopos do OAuth do Gmail declarados
gmail-scopes.py
# Python — Âmbitos da API do Gmail no fluxo OAuth O # utiliza a biblioteca google-auth-oauthlib (biblioteca oficial do Google) from google_auth_oauthlib.flow import FluxoAppInstalado from google.oauth2.credentials import Credenciais from google.auth.transport.requests import Solicitação import os # Definir escopos da API do Gmail — solicite apenas o que você precisa ESCOPOS = [ 'https://www.googleapis.com/auth/gmail.readonly', # restrito 'https://www.googleapis.com/auth/gmail.send', Sensível ao # 'https://www.googleapis.com/auth/gmail.labels', # não sensível ] def obter_credenciais_gmail(): creds = Nenhum # Carregar o token existente, se disponível se os.path.existe('token.json'): creds = Credenciais.do_arquivo_de_usuário_autorizado( 'token.json', ESCOPOS ) # Atualizar ou solicitar novas credenciais se não credenciais ou não creds.valid: se credenciais e creds.expirou e creds.refresh_token: creds.atualizar(Solicitação()) senão: #: Acionar a tela de consentimento do OAuth com escopos declarados flow = FluxoDeAppInstalado.do_arquivo_de_segredos_do_cliente( 'credenciais.json', ESCOPOS ) creds = flow.executar_servidor_local(port=0) #: token de persistência para execuções futuras com abra('token.json', 'w') como token: token.Escrever(creditos.para_json()) return credenciais
Escopos OAuth do Gmail declarados - token persistido em disco

Importante: O consentimento' (Node.js) ou executar_servidor_local chamar (Python) força a tela de consentimento do Google a aparecer mesmo que o usuário já tenha autorizado anteriormente. Isso é necessário para obter confiavelmente um token_de_atualização. Sem um token de atualização, seu token de acesso expira após 1 hora e os usuários precisam autorizar novamente. Para um guia completo sobre como lidar com a atualização de token e reautorização de escopo, consulte o Guia da API de E-mail OAuth e o Documentação do Google OAuth da Unipile.

Conformidade

Princípio do Escopo Mínimo e Conformidade

O princípio do escopo mínimo não é apenas uma recomendação do Google - ele afeta diretamente sua postura de conformidade com o GDPR e o SOC 2. Solicitar permissões excessivas da API do Gmail cria riscos desnecessários de exposição de dados e complica seus acordos de processamento de dados com os usuários finais.

Menos privilégios por design

O princípio do escopo mínimo espelha o conceito de segurança de privilégio mínimo. Sua integração com a API do Gmail deve solicitar o escopo da API do Gmail de menor permissão que permite o recurso. Se o seu CRM envia apenas e-mails de acompanhamento, gmail.enviar é o suficiente gmail.modificar é excessiva e cria um risco desnecessário.

Tela de consentimento clara

O Google exibe os escopos declarados da API do Gmail diretamente na tela de consentimento. Escopos mais amplos acionam linguagem mais alarmante ("Este aplicativo quer acesso a toda a sua caixa de entrada do Gmail"). Escopos mínimos do Gmail OAuth criar telas de consentimento mais simples e menos intimidadoras — o que geralmente aumenta as taxas de conversão de autorização em 15% a 30% nos fluxos OAuth voltados para o usuário.

Documentação de processamento de dados

Sua política de privacidade e o DPA (Acordo de Processamento de Dados) devem refletir com precisão quais dados do Gmail seu aplicativo acessa. Se seu aplicativo solicitar gmail.somente leitura mas sua política de privacidade menciona apenas "envio de e-mails", você tem uma lacuna na documentação GDPR. Correlacione seus escopos declarados da API do Gmail com suas práticas de dados publicadas.

Auditoria de escopo como prática recorrente

Os requisitos de escopo da API do Gmail evoluem à medida que recursos são adicionados ou removidos. Realize uma auditoria de escopo em cada lançamento principal: remova quaisquer permissões da API do Gmail que seu conjunto de recursos atual não exija mais. Escopos não utilizados em sua declaração OAuth são um passivo de conformidade - eles representam acesso a dados que você afirma precisar, mas não utiliza.

GDPR
Alinhamento do GDPR com escopos do Gmail
Limitação de finalidade: os escopos devem corresponder à finalidade específica declarada aos usuários
Minimização de dados: solicitação metadados do gmail em vez de gmail.somente leitura quando o acesso ao corpo não é necessário
Direitos do usuário: a revogação do token deve remover imediatamente o acesso do seu aplicativo ao Gmail
Transparência: a linguagem da tela de consentimento deve corresponder aos dados que você realmente processa
SOC 2
Alinhamento do SOC 2 com os escopos do Gmail
Controle de acesso: documente cada escopo da API do Gmail e sua justificativa de negócios em sua política de controle de acesso
Acesso lógico: a seleção do escopo deve ser revisada e aprovada como parte do seu processo de gerenciamento de mudanças
Monitoramento: registrar todas as alterações de escopo da API do Gmail em sua trilha de auditoria
Gerenciamento de fornecedores: se estiver usando uma plataforma como a Unipile, inclua a atestação de segurança deles em sua revisão de fornecedor

Integração com Gmail pronta para conformidade. A implementação da API do Gmail da Unipile segue o princípio do escopo mínimo por padrão - seu aplicativo solicita apenas os escopos OAuth do Gmail necessários para os recursos que você habilita.

Criar aplicativos Gmail compatíveis
Solução Unipile

Escopos da API do Gmail com Unipile: Pule a Complexidade dos Escopos

Gerenciar escopos da API do Gmail manualmente significa navegar pelo processo de verificação do Google, lidar com a atualização de tokens em caso de mudanças de escopo e atualizar sua documentação de processamento de dados toda vez que você adiciona um recurso. A Unipile abstrai tudo isso, sua equipe se concentra no produto, não em strings de permissão.

Gmail Gmail
Perspectivas Perspectivas
IMAP IMAP
Gmail OAuth pré-verificado

Unipile detém a verificação OAuth do Google para escopos restritos da API do Gmail. Seu aplicativo se beneficia imediatamente sem a necessidade de concluir uma avaliação de segurança separada. A recertificação anual é tratada pela equipe de conformidade da Unipile.

Gerenciamento automático de tokens

Unipile gerencia a atualização de tokens OAuth, a validação de escopo e os fluxos de reautorização para cada uma das contas vinculadas dos seus usuários. Quando o Google atualiza os requisitos de escopo, Unipile se adapta sem quebrar sua integração.

API unificada entre provedores

As mesmas chamadas de API da Unipile funcionam para Gmail, Outlook e IMAP. Você escreve sua funcionalidade de e-mail uma vez e ela funciona em todos os provedores, sem gerenciamento de escopo de API do Gmail separado por provedor, sem ramificações de código específicas de protocolo.

Opção OAuth de marca branca

Para equipes que precisam usar suas próprias credenciais do Google, o Unipile oferece suporte à configuração OAuth de marca branca. Seus usuários veem sua marca na tela de consentimento enquanto o Unipile gerencia a declaração de escopo e o ciclo de vida do token em segundo plano.

Escopo mínimo por padrão

A integração do Gmail da Unipile solicita apenas as permissões da API do Gmail necessárias para os recursos que você habilita. Ler, enviar, sincronizar, cada capacidade é mapeada para o escopo mais restrito possível, mantendo seu perfil de conformidade limpo.

Webhooks em tempo real

Receba novas mensagens do Gmail assim que elas chegam via webhooks Unipile. Sem polling, sem gerenciar assinaturas do Gmail Pub/Sub manualmente. Funciona com o mesmo token OAuth que seu aplicativo já usa para outras operações da API do Gmail.

Nenhuma avaliação de segurança necessária
Gmail, Outlook e IMAP em uma única API
Em conformidade com GDPR e SOC 2
Teste grátis por 14 dias, sem necessidade de cartão
PERGUNTAS FREQUENTES

Perguntas Frequentes sobre Escopos da API do Gmail

Perguntas comuns sobre escopos da API do Gmail, escopos do OAuth do Gmail e o processo de verificação - respondidas de forma concisa para desenvolvedores que criam integrações com o Gmail.

01
Quais são os escopos da API do Gmail?
Escopos da API do Gmail são strings de permissão do OAuth 2.0 que definem exatamente quais recursos do Gmail seu aplicativo pode acessar em nome de um usuário. Elas são declaradas ao gerar a URL de autorização OAuth e exibidas ao usuário na tela de consentimento do Google. Uma vez que um usuário concede acesso, seu token é limitado apenas às ações que esses escopos da API do Gmail permitem - nada mais. Comece com nosso Tutorial completo de integração da API do Gmail.
02
Qual é a diferença entre gmail.readonly e gmail.modify?
Ambos gmail.somente leitura e gmail.modificar são escopos restritos da API do Gmail. gmail.somente leitura concede acesso somente leitura a todas as mensagens, conversas, marcadores e configurações - seu aplicativo não pode enviar ou alterar nada. gmail.modificar adiciona a capacidade de ler, compor, enviar e-mails e gerenciar rótulos, mas exclui a exclusão permanente de mensagens. Se seu aplicativo precisa ler e enviar, mas não excluir, gmail.modificar é preferível à mais ampla mail.google.com/ escopo. Veja nosso como ler e-mails de usuários via uma API unificada.
03
Você precisa de uma avaliação de segurança para todos os escopos da API do Gmail?
Não. Apenas escopos restritos da API do Gmail exigem uma avaliação de segurança anual realizada por terceiros (~1.000 a 4.500 por ano). Âmbitos não confidenciais, como gmail.marcadores exigem apenas a revisão padrão do aplicativo OAuth. Escopos sensíveis como gmail.enviar exigem o processo de verificação do OAuth do Google, mas sem avaliação de segurança. Escopos restritos - incluindo gmail.somente leitura, gmail.modificar, gmail.escrever, metadados do gmail, gmail.inserire mail.google.com/ - exigem o processo completo de avaliação. Mais sobre isso em nosso Padrões de API de e-mail seguro para indústrias regulamentadas.
04
O escopo `gmail.modify` é usado para permitir que um aplicativo modifique as mensagens de e-mail de um usuário na Conta do Google. Isso inclui ações como adicionar marcadores, mover mensagens para outras pastas, marcar como lida ou não lida, arquivar ou excluir mensagens.
O gmail.modificar o escopo concede acesso de leitura, composição, envio e gerenciamento de marcadores ao Gmail, mas exclui a capacidade de excluir permanentemente mensagens. É o escopo restrito recomendado para integrações de e-mail com recursos completos, como Sincronização de e-mail do CRM, ferramentas de helpdesk e clientes de e-mail que precisam tanto ler quanto enviar mensagens. É preferível a mail.google.com/ pois limita a exposição de dados ao excluir a funcionalidade de exclusão permanente. Relacionado: enviando e-mail em nome de usuários.
05
Quantos usuários de teste posso ter antes de concluir a verificação de escopo da API do Gmail?
Você pode testar seu aplicativo com até 100 contas do Google Enquanto seu aplicativo OAuth estiver em modo de teste, independentemente dos escopos da API do Gmail que você declarar. Essas contas de teste devem ser adicionadas manualmente nas configurações da tela de consentimento OAuth do Google Cloud Console. Assim que você exceder 100 usuários ou quiser lançar publicamente, você deve concluir o processo de verificação apropriado para o nível de sensibilidade dos seus escopos.
06
Posso combinar vários escopos do Gmail API em uma única solicitação OAuth?
Sim, você pode combinar vários escopos da API do Gmail em uma única solicitação de autorização OAuth, passando-os como um array para o escopo parâmetro. Por exemplo, você pode solicitar gmail.enviar + gmail.marcadores juntos. No entanto, combinar escopos aumenta as permissões mostradas na tela de consentimento do Google e pode acionar requisitos adicionais de verificação se algum escopo combinado for restrito. Sempre solicite apenas a combinação mínima que seu aplicativo realmente precisa. Para o lado da Microsoft, consulte Microsoft Graph OAuth escopos equivalentes.
07
O que é o escopo gmail.metadata?
O metadados do gmail escopo é um escopo restrito da API do Gmail que concede acesso a cabeçalhos e rótulos de e-mail, sem nenhum acesso ao corpo ou anexos do e-mail. É útil para mecanismos de roteamento, sistemas de categorização ou ferramentas de análise que processam e-mails com base no remetente, destinatário, assunto ou rótulos sem ler o conteúdo das mensagens privadas. Apesar de restrito, possui uma pegada de dados menor que gmail.somente leitura e talvez seja mais fácil de justificar em uma avaliação de segurança. Mergulhamos mais fundo em nosso API de sincronização de e-mail para sincronização completa da caixa de entrada.
08
Como o Unipile lida com os escopos da API do Gmail para o meu aplicativo?
O Unipile gerencia os escopos da API do Gmail internamente como parte de sua integração de OAuth do Gmail hospedada. Quando seus usuários vinculam suas contas do Gmail por meio do Unipile, o Unipile solicita os escopos apropriados do OAuth do Gmail com base nos recursos que você habilita, gerencia a atualização de tokens automaticamente e lida com a reautorização quando os requisitos de escopo mudam. Sua equipe não precisa declarar ou gerenciar listas de escopos da API do Gmail diretamente – e você se beneficia de Verificação Google existente da Unipile status para escopos restritos. Para mais informações sobre isso, consulte nosso comparação de 6 provedores de API de e-mail.
09
O que é o `gmail.send` e quando devo usá-lo?
O gmail.enviar escopo é um escopo sensível da API do Gmail que permite que seu aplicativo envie e-mails em nome de um usuário autenticado, sem conceder acesso de leitura ou modificação a mensagens existentes. É o escopo mínimo recomendado para aplicativos que enviam apenas e-mails - ferramentas de prospecção, sistemas de notificação ou automação de acompanhamento. Usando gmail.enviar em vez de gmail.modificar evita completamente a avaliação de segurança de escopo restrito, acelerando significativamente seu caminho para a produção. Veja nosso Guia dedicado da API de Envio de E-mail.
10
Como os escopos da API do Gmail afetam a conformidade com o GDPR?
Os escopos da API do Gmail afetam diretamente sua postura de GDPR. O Princípio da minimização de dados exige que você solicite apenas as permissões da API do Gmail necessárias para a finalidade declarada. Sua política de privacidade deve refletir com precisão quais dados do Gmail você acessa. Solicitar escopos excessivos cria uma lacuna na documentação do GDPR e aumenta a responsabilidade em caso de violação. Quando os usuários revocam a autorização, seu aplicativo deve perder imediatamente o acesso aos dados do Gmail deles - isso é imposto pela invalidação do token do Google, mas também deve ser refletido em seus procedimentos de exclusão de dados.

Precisa de ajuda para escolher os escopos certos para o seu caso de uso na API do Gmail? Nossa equipe pode revisar sua arquitetura de integração e recomendar o conjunto de escopo mínimo.

Fale com um especialista
pt_BRBR