Escolher escopos da API Gmail

Este documento contém informações de autorização e autenticação específicas da API Gmail. Antes de ler este documento, leia as informações gerais de autenticação e autorização do Google Workspace em Saiba mais sobre autenticação e autorização.

Configurar o OAuth 2.0 para autorização

Configure a tela de permissão OAuth e escolha escopos para definir quais informações serão exibidas aos usuários e revisores de apps e registre seu app para publicá-lo mais tarde.

Escopos da API Gmail

Para definir o nível de acesso concedido ao app, é necessário identificar e declarar os escopos de autorização. Um escopo de autorização é uma string de URI do OAuth 2.0 que contém o nome do app do Google Workspace, o tipo de dados que ele acessa e o nível de acesso. Os escopos são as solicitações do app para trabalhar com os dados do Google Workspace, incluindo os dados da Conta do Google dos usuários.

Quando seu app é instalado, o usuário precisa validar os escopos usados pelo app. Em geral, é preciso escolher o escopo mais restrito possível e evitar a solicitação de escopos que seu app não exige. Os usuários concedem acesso a escopos limitados e claramente descritos.

A API Gmail é compatível com os seguintes escopos:

Código do escopo Descrição Uso
https://www.googleapis.com/auth/gmail.addons.current.action.compose Gerencie rascunhos e envie e-mails quando você interagir com o complemento. Não confidencial
https://www.googleapis.com/auth/gmail.addons.current.message.action Confira suas mensagens de e-mail quando interagir com o complemento. Não confidencial
https://www.googleapis.com/auth/gmail.addons.current.message.metadata Ver os metadados da mensagem de e-mail quando o complemento estiver em execução. Sensível
https://www.googleapis.com/auth/gmail.addons.current.message.readonly Veja suas mensagens de e-mail quando o complemento estiver em execução. Sensível
https://www.googleapis.com/auth/gmail.labels Apenas criar, ler, atualizar e excluir marcadores. Não confidencial
https://www.googleapis.com/auth/gmail.send Enviar apenas mensagens. Nenhum privilégio de leitura ou modificação na caixa de e-mails. Sensível
https://www.googleapis.com/auth/gmail.readonly Ler todos os recursos e os respectivos metadados, sem operações de gravação. Restrito
https://www.googleapis.com/auth/gmail.compose Criar, ler, atualizar e excluir rascunhos. enviar mensagens e rascunhos; Restrito
https://www.googleapis.com/auth/gmail.insert Inserir e importar apenas mensagens. Restrito
https://www.googleapis.com/auth/gmail.modify Todas as operações de leitura/gravação, exceto a exclusão imediata e permanente de linhas de execução e mensagens, ignorando a lixeira. Restrito
https://www.googleapis.com/auth/gmail.metadata Ler metadados de recursos, incluindo rótulos, registros de histórico e cabeçalhos das mensagens de e-mail, mas não o corpo ou os anexos da mensagem. Restrito
https://www.googleapis.com/auth/gmail.settings.basic Gerencie as configurações básicas de e-mail. Restrito
https://www.googleapis.com/auth/gmail.settings.sharing Gerencie configurações de e-mails confidenciais, incluindo regras de encaminhamento e aliases.

Observação:as operações protegidas por esse escopo são restritas apenas ao uso administrativo. Eles só estão disponíveis para clientes do Google Workspace que usam uma conta de serviço com delegação em todo o domínio.
Restrito
https://mail.google.com/ Acesso total às caixas de e-mails da conta, incluindo exclusão permanente de conversas e mensagens Esse escopo só deverá ser solicitado se o aplicativo precisar excluir conversas e mensagens de forma imediata e permanente, ignorando a lixeira. Todas as outras ações podem ser realizadas com escopos menos permissivos. Restrito

A coluna Uso na tabela acima indica a sensibilidade de cada escopo, de acordo com as seguintes definições:

As informações adicionais que regem seu uso e acesso às APIs do Gmail quando você solicita acesso aos dados do usuário podem ser encontradas na Política de dados do usuário e do desenvolvedor dos serviços da API Gmail.

Se o app exigir acesso a outras APIs do Google, também é possível adicionar esses escopos. Para mais informações sobre os escopos da API do Google, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

Verificação do OAuth

O uso de determinados escopos confidenciais do OAuth pode exigir que seu app passe pelo processo de verificação do OAuth do Google. Leia as Perguntas frequentes sobre a verificação do OAuth para determinar quando o app precisa passar pela verificação e o tipo de verificação necessário. Consulte também a página Serviços da API do Google: política de dados do usuário.