Escopos da API do Gmail Explicados: Escolha o Permissões Corretas para o seu aplicativo
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 envie seu fluxo OAuth mais rápido.
// 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',
});O que são Escopos da API do Gmail?
Antes de escrever uma única 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.
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 acesso com base nesses escopos. Uma vez concedido, seu token de acesso é limitado exatamente às ações que esses escopos permitem – nada mais.
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 token não pode enviar ou excluir e-mails. Escopos são aplicados no lado do servidor pelo 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.
Solicitar mais permissões da API do Gmail do que o seu aplicativo precisa aciona um aviso "Este app quer amplo acesso à 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.
Pular o gerenciamento de escopo completamente. Unipile lida com OAuth e escopos do Gmail internamente - sua equipe foca na lógica do produto, não em strings de permissão.
Construa com UnipileOs 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 com o Gmail.
O nível de menor risco. Esses escopos acessam dados limitados e não pessoais do Gmail. O Google não exige uma avaliação formal de segurança para utilizá-los em produção.
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.
Maior nível de risco. 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.
| Critérios | Não sensível | Sensível | Restrito |
|---|---|---|---|
| Acessos ao corpo da mensagem | Não | Às vezes | Sim |
| Avaliação de segurança necessária | Não | Não | Sim |
| Revisão de 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) |
Referência Completa do 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. Os escopos marcados com "2026" refletem as últimas adições à 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 extensões criem 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 mensagem (arquivar, rotular) no contexto da mensagem |
| gmail.marcadores 2026 | Não sensível | Ver e editar etiquetas (criar, renomear, excluir), mas não o conteúdo das mensagens | Aplicativos que organizam e-mail com marcadores 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 add-on - não no 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 para leitura ao e-mail atual, incluindo corpo e anexos, no contexto do complemento | Complementos que analisam ou extraem dados da mensagem atualmente 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, compor, enviar e excluir permanentemente e-mails e configurações | Somente quando você precisa de todas as funcionalidades 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, busca 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 e-mails existentes | Ferramentas de gerenciamento de rascunhos, compostores de e-mail ou aplicativos que colocam e-mails em fila antes de enviar |
| gmail.inserir 2026 | Restrito | Inserir mensagens na caixa de entrada do Gmail apenas - não é possível ler ou enviar emails 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 necessitam de ler+enviar+rotular |
| metadados do gmail | Restrito | Cabeçalhos e rótulos apenas - sem acesso ao corpo do email ou anexos | Aplicativos que categorizam ou roteiam e-mails com base em metadados sem ler o conteúdo privado |
| gmail.configurações.básico | Restrito | Gerenciar configurações básicas do Gmail: filtros, regras de encaminhamento, configurações POP/IMAP | Ferramentas de produtividade de e-mail que configuram o roteamento ou a 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 de férias (apenas administrador do domínio) | Ferramentas de administrador do Workspace - requer privilégios de administrador de domínio para habilitar |
Não gerencie estes escopos da API do Gmail manualmente. A integração de Gmail da Unipile lida com solicitações de escopo OAuth, atualização de tokens e fluxos de re-autorização automaticamente em todas as contas vinculadas dos seus usuários.
Crie seu aplicativo GmailQual Escopo da API do Gmail Você Precisa?
O princípio mais importante na seleção de escopos da API do Gmail é o princípio do 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 emails apenas (não ler caixa de entrada) | gmail.enviar | Sensível | Ideal para ferramentas transacionais ou de prospecção. Sem acesso a mensagens existentes. |
| Ler caixa de entrada para análises ou buscar | gmail.somente leitura | Restrito | Acesso completo de leitura a todas as mensagens e configurações. Requer avaliação anual de segurança. |
| Cliente de e-mail completo (ler + enviar + rotular) | gmail.modificar | Restrito | Preferido a mail.google.com/ pois exclui a exclusão permanente. Cobre a maioria dos casos de uso de CRM e helpdesk. |
| Arquivar ou fazer backup de e-mails permanentemente | mail.google.com/ | Restrito | Use somente quando realmente precisar de acesso para excluir. Aciona o aviso de consentimento mais amplo do Google. |
| Organizar apenas rótulos | gmail.marcadores | Não sensível | Novidade em 2026. Permissões mínimas para gerenciamento de marcações sem leitura de mensagens. |
| Gerenciamento de rascunhos (fila antes de enviar) | 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. Bom para mecanismos de roteamento que respeitam a privacidade da mensagem. |
| Migração / importação de e-mail para o Gmail | gmail.inserir | Restrito | Novo em 2026. Acesso somente de inserção - alternativa com escopo melhor para mail.google.com/ para importar ferramentas. |
| Configurar filtros e encaminhamento do Gmail | gmail.configurações.básico | Restrito | Gerenciar filtros, marcadores, 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 somente no contexto do complemento. Evita acesso total à leitura da mensagem. |
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 revise sua lista de escopos antes de ir para produção. Se você está construindo um produto de sincronização completa do Gmail, o Guia da API de E-mail OAuth cobre o fluxo completo, incluindo gerenciamento de tokens e reautorização de escopo.
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ê precisa concluir o processo de avaliação de segurança do Google antes de publicar para mais de 100 usuários de teste. Veja como é esse processo e como minimizar a sobrecarga.
Crie um projeto, ative a API do Gmail e configure a tela de consentimento do OAuth. Preencha todos os campos obrigatórios: nome do app, 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.
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 a um avaliador de segurança.
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.
Os 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 esse custo recorrente e ciclo de conformidade desde o primeiro dia da arquitetura de sua integração com o Gmail.
Escolher gmail.enviar sobre gmail.modificar quando seu aplicativo só envia e-mails e não precisa ler a caixa de entrada. gmail.enviar é um escopo sensível (não restrito) e pula a avaliação de segurança inteiramente.
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 hojeComo 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.
// 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;
}# 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 credenciaisImportante: 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.
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.
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.
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.
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.
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.
metadados do gmail em vez de gmail.somente leitura quando o acesso ao corpo não é necessário
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íveisEscopos 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 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 foca no produto, não em strings de permissão.
Unipile detém a verificação OAuth do Google para escopos restritos da API do Gmail. Seu aplicativo se beneficia imediatamente sem concluir uma avaliação de segurança separada. A recertificação anual é tratada pela equipe de conformidade da Unipile.
Unipile gerencia fluxos de atualização de token OAuth, validação de escopo e reautorização para cada conta vinculada de seus usuários. Quando o Google atualiza os requisitos de escopo, o Unipile se adapta sem quebrar sua integração.
As mesmas chamadas de API 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.
Para equipes que precisam usar suas próprias credenciais do Google, o Unipile suporta configuração OAuth white-label. 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.
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.
Receba novas mensagens do Gmail assim que elas chegam via webhooks do 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.
Perguntas Frequentes sobre Escopos da API do Gmail
Perguntas comuns sobre escopos da API do Gmail, escopos OAuth do Gmail e o processo de verificação - respondidas de forma concisa para desenvolvedores que criam integrações com o Gmail.
gmail.somente leitura e gmail.modificar são escopos restritos da API do Gmail. gmail.somente leitura fornece 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 marcadores, mas exclui a exclusão permanente de mensagens. Se seu aplicativo precisar ler e enviar, mas não excluir, gmail.modificar é preferível em vez do mais amplo mail.google.com/ escopo. Veja nosso como ler e-mails de usuários via uma API unificada.gmail.marcadores requer apenas revisão padrão do aplicativo OAuth. Escopos sensíveis como gmail.enviar requerem o processo de verificação 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 setores regulamentados.gmail.modificar O escopo concede acesso de leitura, composição, envio e gerenciamento de rótulos ao Gmail, mas exclui a capacidade de excluir permanentemente mensagens. É o escopo restrito recomendado para integrações de e-mail com todos os recursos, como Sincronização de e-mail do CRM, ferramentas de helpdesk e clientes de e-mail que precisa 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: enviar e-mail em nome de usuários.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 de verificação adicionais se algum escopo combinado for restrito. Sempre solicite apenas a combinação mínima que seu aplicativo realmente precisa. Do lado da Microsoft, veja Escopos OAuth equivalentes do Microsoft Graph.metadados do gmail escopo é um escopo restrito da API do Gmail que concede acesso a cabeçalhos e marcadores de e-mail apenas, sem qualquer acesso ao corpo do e-mail ou anexos. É útil para mecanismos de roteamento, sistemas de categorização ou ferramentas analíticas que processam e-mails com base no remetente, destinatário, assunto ou rótulos sem ler o conteúdo privado da mensagem. Apesar de restrito, possui uma pegada de dados menor do que gmail.somente leitura e pode ser 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.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 comunicação, sistemas de notificação ou automação de acompanhamento. Usando gmail.enviar em vez de gmail.modificar evitando completamente a avaliação de segurança de escopo restrito, acelerando significativamente seu caminho para a produção. Veja nosso Guia da API dedicada de envio de e-mail.