Para administradores
← Todos os tópicos

Google Workspace: conectar caixas de e-mail

A conexão com a conta da caixa de e-mail (cliente da organização) e, além disso, uma conta de serviço para caixas compartilhadas – e o que configurar no Google Cloud e no Google Admin, passo a passo.

Para ler os e-mails no Google Workspace e criar rascunhos neles, o assistente precisa de acesso pela Gmail API. Para isso, a organização cria algo no próprio Google Cloud; o draften não tem um aplicativo comum ao qual você só daria consentimento. Isso vale tanto para o nosso serviço quanto para a instalação no seu próprio servidor.

Tudo aqui vale só para contas do Google Workspace com domínio próprio. Com uma conta pessoal @gmail.com não dá para entrar no draften; mas o Gmail pessoal você conecta por IMAP com senha de app – veja Provedores compatíveis e limitações.

O que você quer e o que configurar

O que você querO que configurar
Os membros entram com a conta Google e cada um tem a própria caixa de e-mailcliente da organização – isso basta
Além disso, caixas de e-mail nas quais ninguém entra (por exemplo info@), ou o acesso às caixas de e-mail configurado de forma central, sem os proprietários delastambém o registro da organização (conta de serviço)
Você não quer a entrada com conta Googleas pessoas entram com a senha do convite, e os e-mails são conectados pelo registro da organização (ou por IMAP)

Duas coisas diferentes no Google

O cliente da organização e o registro da organização são duas coisas separadas no Google Cloud. Cada uma faz algo diferente, e uma não substitui a outra:

Cliente da organizaçãoRegistro da organização
O que écliente OAuth com consent screen do tipo Internalconta de serviço com chave e domain-wide delegation
O que faza entrada dos membros com o botão Entrar com o Google e o botão Conectar o Gmail na própria caixa de e-mailo acesso do assistente às caixas de e-mail sem que os proprietários delas entrem
Onde fica no draftenOrganização → Entrada e acesso aos e-mails → cartão Entrada com conta e conexão de caixas de e-mailOrganização → Entrada e acesso aos e-mails → cartão Registros para caixas compartilhadas e gestão central
Quem o configura no drafteno proprietário da organizaçãoo proprietário ou um administrador da organização
Quem o cria no Googleum administrador do Google Cloudum administrador do Google Cloud e um superadministrador do Google Admin
Quem entra na caixa de e-mailo proprietário de cada caixa de e-mail, uma vezninguém
Quais caixas de e-mail alcançasó as que as próprias pessoas conectamtodas as caixas do domínio

São duas coisas de propósito. O consentimento para o cliente dá direitos só às caixas de e-mail que as próprias pessoas conectam – nunca aos e-mails de todo o domínio. A conta de serviço, ao contrário, alcança qualquer caixa do domínio, e por isso o draften a usa só para o acesso às caixas de e-mail, nunca para a entrada. Não as junte.

Cada caixa de e-mail usa um dos dois acessos; você pode ter os dois ao mesmo tempo. O draften pede só o escopo gmail.modify – leitura e criação de rascunhos; ele não envia nada.

Cliente da organização: entrada e Conectar o Gmail

O proprietário da caixa de e-mail entra com a conta Google dele e permite o acesso só aos próprios e-mails. O mesmo cliente serve também para entrar no draften com a conta Google.

No Google Cloud

Você trabalha em https://console.cloud.google.com, conectado com a conta de administrador do seu domínio do Workspace. Tudo acontece em um só projeto – o projeto escolhido aparece no alto, à esquerda, ao lado do logotipo do Google Cloud; ali você também o troca ou cria um novo. O menu principal você abre com o ícone ☰ no canto superior esquerdo.

  1. No draften, abra primeiro Organização → Entrada e acesso aos e-mails, o cartão Entrada com conta e conexão de caixas de e-mail. Ele mostra duas redirect URIs exatamente para o endereço do seu draften – terminam em /auth/google/callback e /mailboxes/connect/google/callback. Copie-as de lá; elas precisam coincidir caractere por caractere.
  2. Escolha um projeto ou crie um novo (por exemplo draften) e ative nele a Gmail API: ☰ → APIs & Services → Library, procure Gmail API, abra-a e clique em Enable. Direto: https://console.cloud.google.com/apis/library/gmail.googleapis.com
  3. Defina como o aplicativo se apresenta aos usuários (consent screen): ☰ → APIs & Services → OAuth consent screen. Abre-se a página Google Auth Platform; direto: https://console.cloud.google.com/auth/overview (confira se o projeto certo está escolhido no alto). Clique em Get started e percorra o assistente:
    • App Information – App name draften e User support email (o seu e-mail ou um grupo de administradores). Next.
    • Audience – escolha Internal. Assim só contas do seu domínio do Workspace podem entrar e o Google não precisa verificar o aplicativo. Next.
    • Contact Information – o e-mail para o qual o Google enviará avisos sobre o aplicativo. Next.
    • Finish – marque a caixa de concordância com as políticas do Google (I agree to the Google API Services: User Data Policy), clique em Continue e depois em Create.
  4. Libere os escopos para o aplicativo. Na Google Auth Platform, no menu à esquerda, abra Data Access (direto: https://console.cloud.google.com/auth/scopes) → Add or remove scopes. Na lista, marque openid, .../auth/userinfo.email e .../auth/userinfo.profile. O escopo do Gmail você cola no campo Manually add scopes: https://www.googleapis.com/auth/gmail.modify → Add to table. Clique em Update e, embaixo, em Save.
  5. Crie o cliente. Na Google Auth Platform, no menu à esquerda, abra Clients (direto: https://console.cloud.google.com/auth/clients) → Create client. Application type: Web application, nome por exemplo draften. Em Authorized redirect URIs, clique em Add URI e cole o primeiro endereço do cartão; depois, de novo Add URI e o segundo. Clique em Create.
  6. Aparecem o Client ID e o Client secret – copie os dois na hora. O Google não mostra mais o Client secret depois; se você o perder, crie um novo no cliente.

No draften

  1. O proprietário da organização abre Organização → Entrada e acesso aos e-mails e, no cartão Entrada com conta e conexão de caixas de e-mail, preenche em Cliente OAuth do Google os valores Client ID e Client secret do passo 6 e clica em Salvar.
  2. A entrada com conta Google ele ativa na mesma página, no cartão Como os membros entram: em Domínios de e-mail da organização, escreve o seu domínio do Workspace – o principal, não um alias (esse o Google não envia ao entrar). Assim que a organização tiver o cliente e o domínio, os membros entram com a conta Google e as senhas deles deixam de funcionar – veja Como os membros entram.
  3. O proprietário da caixa de e-mail abre a página da caixa e, no cartão Acesso aos e-mails, na linha Conectar com a conta da caixa de e-mail:, clica em Conectar o Gmail. Ele entra com a conta dessa caixa de e-mail – o draften recusa outra conta – e permite o acesso. Só o proprietário da caixa vê o botão, e só quando a organização tem o cliente; sem ele, o cartão mostra no lugar do botão que a conexão com a conta vai ser possível quando o proprietário da organização adicionar o cliente.
  4. Depois, Testar a conexão.

Quando a caixa de e-mail se desconecta

Registro da organização: acesso sem entrar

Uma conta de serviço com domain-wide delegation dá ao assistente acesso às caixas de e-mail do domínio sem que ninguém precise entrar. Ela serve para caixas de e-mail nas quais ninguém entra (por exemplo info@) e para organizações que querem gerenciar o acesso de forma central. Não tem relação com a entrada no draften.

No Google Cloud

Você trabalha em https://console.cloud.google.com, no mesmo projeto em que a Gmail API está ativada (passo 2 do cliente da organização; sem o cliente, ative-a do mesmo jeito). Confira o projeto no alto, à esquerda, ao lado do logotipo do Google Cloud.

  1. Abra a lista de contas de serviço: ☰ → IAM & Admin → Service accounts. Direto: https://console.cloud.google.com/iam-admin/serviceaccounts
  2. No alto, clique em + Create service account e percorra as três etapas:
    • Service account details – Service account name por exemplo draften-emails (o ID é preenchido sozinho). Clique em Create and continue.
    • Permissions (optional) – não escolha nada; ela não precisa de nenhuma role no projeto, o acesso aos e-mails vem só da delegação no Google Admin. Clique em Continue.
    • Principals with access (optional) – não preencha nada, clique em Done.
  3. Na lista, clique na nova conta de serviço. Na aba Details, copie o Unique ID – um número longo; esse é o Client ID para o Google Admin.
  4. Aba Keys → Add key → Create new key → Key type: JSON → Create. O navegador baixa um arquivo com a chave (….json).

Se o Google recusar a criação da chave, a sua organização tem ativada a política Disable service account key creation (iam.disableServiceAccountKeyCreation; organizações novas a têm por padrão). Um administrador da organização a desativa para este projeto: ☰ → IAM & Admin → Organization policies (https://console.cloud.google.com/iam-admin/orgpolicies), procura iam.disableServiceAccountKeyCreation → Manage policy → Override parent's policy → Enforcement: Off → Set policy. Depois, repita o passo 4.

No Google Admin

Você precisa de uma conta de superadministrador do Google Workspace.

  1. Abra https://admin.google.com → no menu à esquerda, Security → Access and data control → API controls → embaixo, Domain wide delegation → Manage domain wide delegation. Direto: https://admin.google.com/ac/owl/domainwidedelegation
  2. Clique em Add new e preencha:
    • Client ID – o Unique ID numérico do passo 3,
    • OAuth scopes (comma-delimited) – https://www.googleapis.com/auth/gmail.modify.

    Clique em Authorize. A delegação aparece na lista. Ela costuma entrar em vigor em poucos minutos, excepcionalmente só depois de algumas horas.

No draften

  1. Abra Organização → Entrada e acesso aos e-mails, o cartão Registros para caixas compartilhadas e gestão central. Os registros são gerenciados pelo proprietário ou por um administrador da organização.
  2. Sistema: Google Workspace. Preencha Nome, escolha o arquivo baixado em Chave da conta de serviço (JSON) e clique em Adicionar registro. A chave é guardada criptografada; depois, o cartão mostra só o e-mail da conta de serviço e o Client ID dela.
  3. Na página de cada caixa de e-mail, no cartão Acesso aos e-mails, escolha este registro em Registro da organização, clique em Aplicar e depois em Testar a conexão. O procedimento, com capturas de tela, está no guia Adicionar e conectar uma caixa de e-mail.

Depois, apague o arquivo da chave que você baixou. Quem o tiver entra em qualquer caixa de e-mail do domínio. Uma nova chave da mesma conta de serviço (passo 4 acima) você carrega no registro com a opção nova chave (JSON); a chave de outra conta de serviço, adicione como um novo registro. Depois, apague a chave antiga no Google Cloud: conta de serviço → aba Keys → ícone de lixeira ao lado da chave antiga.

Com a caixa de e-mail automática ativada (Como os membros entram), uma nova caixa de e-mail é vinculada sozinha ao registro quando há exatamente um ativo para o Google Workspace.

Erros do teste de conexão

O teste verifica três etapas: Acesso, Token e permissão e Leitura da Caixa de Entrada.

Na mensagemO que significaO que fazer
a delegação para o escopo não está permitida (unauthorized_client)falta a domain-wide delegation no Google Admin, ou ela tem outro Client ID ou outro escopoconferir a delegação no Google Admin: o ID numérico e o escopo exato gmail.modify
invalid_grant na conta de serviçoessa caixa de e-mail não existe no domínio do Workspaceconferir o endereço da caixa de e-mail
“Gmail API has not been used…”a Gmail API não está ativada no projetoativar a Gmail API
token sem gmail.modifya delegação ou a consent screen não tem o escopo gmail.modifyincluir o escopo
invalid_grant, deleted_client na conta conectadaa conexão foi revogada ou o cliente foi apagadoReconectar o Gmail

Outros erros estão em Solução de problemas.

Versão em texto