Este documento contém informações de autorização e autenticação específicas da API Gmail. Antes de ler este documento, confira 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 do OAuth e escolha escopos para definir quais informações são mostradas aos usuários e revisores de apps e registre o app para poder publicá-lo mais tarde.
Escopos da API Gmail
Para definir o nível de acesso concedido ao seu app, é necessário identificar e declarar escopos de autorização. Um escopo de autorização é uma string URI do OAuth 2.0 que contém o nome do app do Google Workspace, o tipo de dados acessados e o nível de acesso. Os escopos são solicitações do app para trabalhar com dados do Google Workspace, incluindo dados da Conta do Google dos usuários.
Quando o app é instalado, o usuário precisa validar os escopos usados por ele. Em geral, escolha o escopo mais restrito possível e evite solicitar escopos que o app não precisa. Os usuários concedem acesso mais facilmente 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 |
Gerenciar rascunhos e enviar e-mails quando você interagir com o complemento. | Não sensível |
https://www.googleapis.com/auth/gmail.addons.current.message.action |
Ver suas mensagens de e-mail quando você interagir com o complemento. | Não sensível |
https://www.googleapis.com/auth/gmail.addons.current.message.metadata |
Ver os metadados de mensagens de e-mail quando o complemento estiver em uso. | Sensível |
https://www.googleapis.com/auth/gmail.addons.current.message.readonly |
Ver suas mensagens de e-mail quando o complemento está em execução. | Sensível |
https://www.googleapis.com/auth/gmail.labels |
Criar, ler, atualizar e excluir apenas rótulos. | Não sensível |
https://www.googleapis.com/auth/gmail.send |
Enviar apenas mensagens. Não há privilégios de leitura ou modificação na caixa de correio. | Sensível |
https://www.googleapis.com/auth/gmail.readonly |
Ler todos os recursos e 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 conversas e mensagens, ignorando a Lixeira. | Restrito |
https://www.googleapis.com/auth/gmail.metadata |
Ler metadados de recursos, incluindo marcadores, registros de histórico e cabeçalhos de mensagens de e-mail, mas não o corpo da mensagem ou os anexos. | Restrito |
https://www.googleapis.com/auth/gmail.settings.basic |
Gerenciar configurações de e-mail básicas. | Restrito |
https://www.googleapis.com/auth/gmail.settings.sharing |
Gerenciar configurações de e-mail sensíveis, incluindo regras de encaminhamento e aliases.
Observação:as operações protegidas por esse escopo são restritas apenas ao uso administrativo. Eles estão disponíveis apenas 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 correio da conta, incluindo a exclusão permanente de conversas e mensagens. Esse escopo só deve ser solicitado se o aplicativo precisar excluir conversas e mensagens imediatamente e de forma 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:
Não sensíveis: esses escopos oferecem a menor esfera de acesso de autorização e exigem apenas a verificação básica do app. Para mais informações sobre esse requisito, consulte Etapas para se preparar para a verificação.
Sensíveis: esses escopos permitem acesso aos dados do usuário do Google e exigem um processo de verificação de escopo sensível. Para mais informações sobre esse requisito, consulte Política de dados do usuário dos serviços de API do Google. Esses escopos não exigem uma avaliação de segurança.
Restrito: esses escopos oferecem amplo acesso aos dados de usuário do Google e exigem um processo de verificação de escopo restrito. Para mais informações sobre esse requisito, consulte Política de dados do usuário dos serviços da API do Google e Requisitos adicionais para escopos de API específicos. Se você armazenar dados de escopo restrito em servidores (ou transmitir), será necessário passar por uma avaliação de segurança.
Outras informações que regem seu uso e acesso às APIs do Gmail quando você solicita acesso a dados do usuário podem ser encontradas na Política para desenvolvedores e de dados do usuário dos serviços da API Gmail.
Se o app precisar de acesso a outras APIs do Google, adicione esses escopos também. Para mais informações sobre os escopos das APIs do Google, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.
Verificação do OAuth
O uso de determinados escopos OAuth sensíveis 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 seu app precisa passar por verificação e qual tipo de verificação é necessário. Consulte também a Política de dados do usuário dos serviços de API do Google.