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 consentimento do OAuth e escolha os escopos para definir quais informações são exibidas para usuários e revisores de apps e registre seu app para poder 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 OAuth 2.0 que contém o nome do app do Google Workspace, o tipo de dados acessado e o nível de acesso. Os escopos são as 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. Geralmente, escolha o escopo mais focado possível e evite solicitar escopos que o app não exige. Os usuários concedem acesso mais fácil a escopos limitados e claramente descritos.
A API Gmail oferece suporte aos 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 |
Acessar 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 |
Acessar os metadados de mensagens de e-mail quando o complemento está em uso. | Sensível |
https://www.googleapis.com/auth/gmail.addons.current.message.readonly |
Acessar suas mensagens de e-mail quando o complemento estiver em execução. | Sensível |
https://www.googleapis.com/auth/gmail.labels |
Criar, ler, atualizar e excluir apenas marcadores. | Não sensível |
https://www.googleapis.com/auth/gmail.send |
Enviar mensagens apenas. Sem 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 os metadados deles, 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 rótulos, 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 básicas de e-mail. | Restrito |
https://www.googleapis.com/auth/gmail.settings.sharing |
Gerenciar configurações de e-mail sensível, incluindo regras de encaminhamento e aliases.
Observação:as operações protegidas por esse escopo são restritas apenas ao uso administrativo. Elas 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 app precisar excluir conversas e mensagens imediatamente e permanentemente, 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ível: 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.
Confidencial: esses escopos permitem acesso aos dados do usuário do Google e exigem um processo de verificação de escopo confidencial. Para saber mais sobre esse requisito, consulte Serviços de API do Google: política de dados do usuário. 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 que você passe por 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 de API do Google e Requisitos adicionais para escopos específicos da API. Se você armazena dados de escopo restrito em servidores (ou os transmite), é necessário fazer uma avaliação de segurança.
Outras informações 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 de desenvolvedores dos serviços da API Gmail.
Se o app precisar de acesso a outras APIs do Google, você também poderá adicionar esses escopos. 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 o app precisa passar pela verificação e que tipo de verificação é necessário. Consulte também a Política de dados do usuário dos serviços de API do Google.