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 que ele acessa 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 exige. Os usuários concedem acesso mais facilmente a escopos limitados e claramente descritos.
Sempre que possível, use escopos não sensíveis para restringir o acesso apenas aos recursos específicos necessários para um app.
Escopos não confidenciais
Os seguintes escopos da API Gmail são recomendados para a maioria dos casos de uso:
| Código do escopo | Descrição |
|---|---|
https://www.googleapis.com/auth/gmail.addons.current.action.compose |
Gerenciar rascunhos e enviar e-mails quando você interagir com o complemento. |
https://www.googleapis.com/auth/gmail.addons.current.message.action |
Ver suas mensagens de e-mail quando você interagir com o complemento. |
https://www.googleapis.com/auth/gmail.labels |
Ver e editar os marcadores do seu e-mail. |
Escopos confidenciais
| Código do escopo | Descrição |
|---|---|
https://www.googleapis.com/auth/gmail.addons.current.message.metadata |
Ver os metadados da sua mensagem de e-mail quando o complemento estiver sendo executado. |
https://www.googleapis.com/auth/gmail.addons.current.message.readonly |
Ver suas mensagens de e-mail quando o complemento está sendo executado. |
https://www.googleapis.com/auth/gmail.send |
Enviar e-mail no seu nome. |
Escopos restritos
| Código do escopo | Descrição |
|---|---|
https://mail.google.com/ |
Ler, escrever, enviar e excluir permanentemente todos os seus e-mails do Gmail.
Observação:solicite esse escopo apenas se o aplicativo precisar excluir conversas e mensagens imediatamente e de forma permanente, sem passar pela lixeira. Você pode realizar todas as outras ações usando escopos menos permissivos. |
https://www.googleapis.com/auth/gmail.readonly |
Ver suas mensagens de e-mail e configurações. |
https://www.googleapis.com/auth/gmail.compose |
Gerenciar rascunhos e enviar e-mails. |
https://www.googleapis.com/auth/gmail.insert |
Adicione mensagens à caixa de e-mails do Gmail. |
https://www.googleapis.com/auth/gmail.modify |
Ler, escrever e enviar e-mails da sua conta do Gmail. Esse escopo não permite a exclusão imediata e permanente de conversas e mensagens, ignorando a lixeira. |
https://www.googleapis.com/auth/gmail.metadata |
Ver os metadados da mensagem de e-mail, como marcadores e cabeçalhos, mas não o corpo do e-mail. |
https://www.googleapis.com/auth/gmail.settings.basic |
Ver, editar, criar ou mudar seus filtros e suas configurações de e-mail no Gmail. |
https://www.googleapis.com/auth/gmail.settings.sharing |
Gerenciar todas as configurações confidenciais, inclusive quem pode gerenciar seu e-mail.
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. |
Os escopos nas tabelas anteriores indicam a sensibilidade deles, de acordo com as seguintes definições:
Não sensíveis: esses escopos fornecem o menor escopo de autorização e exigem apenas a Verificação de apps OAuth básica. Para mais informações, consulte Requisitos de verificação.
Sensíveis: esses escopos fornecem acesso a dados específicos do usuário do Google que os usuários autorizam para seu app. Eles exigem verificação do app OAuth adicional. Para mais informações, consulte Requisitos de escopo sensível e restrito.
Restrito: esses escopos oferecem amplo acesso aos dados do usuário do Google e exigem a verificação de apps OAuth com escopo restrito. Para mais informações, consulte a Política de dados do usuário dos serviços de API do Google e os Requisitos adicionais para escopos de API específicos.
Se você armazenar (ou transmitir) dados de escopo restrito em servidores, 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 aos dados do usuário podem ser encontradas na Política de dados do usuário e de desenvolvedores das APIs do Google Workspace.
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.
Para mais informações sobre escopos específicos do OAuth 2.0, consulte Escopos do OAuth 2.0 para APIs do Google.
Verificação do OAuth
O uso de determinados escopos OAuth sensíveis pode exigir que seu app conclua o processo de verificação do OAuth do Google. As perguntas frequentes sobre a verificação de apps OAuth podem ajudar você a determinar se isso é necessário e qual tipo de verificação é exigido.