Para ler os e-mails no Google Workspace e criar rascunhos neles, o assistente precisa de acesso pela Gmail API. Há dois caminhos, e os dois se apoiam no que a organização cria 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.
Contamos com o Google Workspace. Contas pessoais @gmail.com não são compatíveis: não dá para entrar no draften com elas, e conectá-las exigiria que o Google verificasse o aplicativo.
Qual caminho escolher
| Para toda a organização | Com a conta da caixa de e-mail | |
|---|---|---|
| No draften | registro (conta de serviço) em Organização → Integrações | o botão Conectar o Gmail na caixa de e-mail |
| No Google | conta de serviço com chave e domain-wide delegation | cliente OAuth e consent screen do tipo Internal |
| Quem cria | um administrador do Google Cloud e um superadministrador do Google Admin | um administrador do Google Cloud |
| Quem precisa entrar | ninguém | o proprietário de cada caixa de e-mail, uma vez |
| Quais caixas de e-mail alcança | todas as caixas do domínio | só a caixa cuja conta entrou |
| Entrar no draften com a conta Google | não, isso é outra coisa | o mesmo cliente OAuth serve também para entrar |
Para uma organização com várias caixas de e-mail, o caminho para toda a organização é mais simples. Com a conta da caixa de e-mail convém quando você não quer dar a uma única chave acesso a todas as caixas do domínio, ou quando vai adotar de qualquer forma a entrada com conta Google.
Você pode usar os dois caminhos ao mesmo tempo; cada caixa de e-mail usa um deles. O draften pede só o escopo gmail.modify – leitura e criação de rascunhos; ele não envia nada.
Caminho A: para toda a organização
No Google Cloud
Você trabalha em https://console.cloud.google.com, na organização do seu domínio do Workspace.
- Escolha um projeto ou crie um novo (por exemplo
draften). - APIs & Services → Library → Gmail API → Enable.
- IAM & Admin → Service accounts → Create service account. Um nome, por exemplo
draften-emails. Ela não precisa de nenhuma role do IAM no projeto – o acesso aos e-mails vem só da delegação no Google Admin. Clique em Done. - Abra a conta de serviço e anote o Unique ID dela – o Client ID numérico.
- Aba Keys → Add key → Create new key → JSON → Create. Um arquivo com a chave é baixado.
Se o Google recusar a criação da chave, a sua organização tem ativada a política iam.disableServiceAccountKeyCreation (organizações novas a têm por padrão). Um administrador da organização a desativa para este projeto em IAM & Admin → Organization policies.
No Google Admin
Você precisa de um superadministrador. Em https://admin.google.com, abra Security → Access and data control → API controls → Manage Domain Wide Delegation → Add new. Client ID: o ID numérico do passo 4. OAuth scopes: https://www.googleapis.com/auth/gmail.modify. Clique em Authorize. A delegação costuma entrar em vigor em poucos minutos, excepcionalmente só depois de algumas horas.
No draften
- Abra Organização → Integrações, o cartão Acesso aos e-mails de toda a organização. Os registros são gerenciados pelo proprietário ou por um administrador da organização.
- 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.
- Na página de cada caixa de e-mail, no cartão Acesso aos e-mails, escolha este registro em Usar, 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 você carrega no registro com a opção nova chave (JSON); a chave de outra conta de serviço, adicione como um novo registro. Apague a chave antiga no Google Cloud.
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.
Caminho B: com a conta da caixa de e-mail (Conectar o Gmail)
Aqui 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 OAuth serve também para entrar no draften com a conta Google.
No Google Cloud
- No draften, abra primeiro Organização → Como os membros entram, 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/callbacke/mailboxes/connect/google/callback. Copie-as de lá; elas precisam coincidir caractere por caractere. - No projeto com a Gmail API ativada (passo 2 do caminho A), abra APIs & Services → OAuth consent screen. User type: Internal – assim só contas do seu domínio podem entrar e o Google não precisa verificar o aplicativo. Preencha o nome do aplicativo (por exemplo
draften) e um e-mail de contato. - Na parte dos escopos (Scopes / Data access), adicione
openid,email,profileehttps://www.googleapis.com/auth/gmail.modify. - APIs & Services → Credentials → Create credentials → OAuth client ID. Application type: Web application. Em Authorized redirect URIs, coloque os dois endereços do cartão e clique em Create.
- Copie o Client ID e o Client secret.
No draften
- O proprietário da organização, 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 e clica em Salvar.
- O proprietário da caixa de e-mail abre a página da caixa e, no cartão Acesso aos e-mails, 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 OAuth.
- Depois, Testar a conexão.
A entrada com conta Google você ativa na mesma página: em Domínios de e-mail da organização, escreva 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 OAuth e o domínio, os membros entram com a conta Google e as senhas deles deixam de funcionar – veja Como os membros entram.
Quando a caixa de e-mail se desconecta
- A conta foi apagada ou bloqueada, ou o acesso foi revogado – o Google deixa de emitir tokens e o draften desconecta a caixa de e-mail. Conecte-a de novo (Reconectar o Gmail) ou pelo caminho A.
- “O provedor não emitiu um token de atualização” – o proprietário da caixa de e-mail remove o app nas configurações da conta Google dele (Segurança → Apps de terceiros) e conecta a caixa de novo.
- “Entrou uma conta diferente do endereço da caixa de e-mail” – ao conectar, escolha a conta exatamente dessa caixa de e-mail.
Erros do teste de conexão
O teste verifica três etapas: Acesso, Token e permissão e Leitura da Caixa de Entrada.
| Na mensagem | O que significa | O 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 escopo | conferir a delegação no Google Admin: o ID numérico e o escopo exato gmail.modify |
invalid_grant na conta de serviço | essa caixa de e-mail não existe no domínio do Workspace | conferir o endereço da caixa de e-mail |
| “Gmail API has not been used…” | a Gmail API não está ativada no projeto | ativar a Gmail API (passo 2) |
token sem gmail.modify | a delegação ou a consent screen não tem o escopo gmail.modify | incluir o escopo |
invalid_grant, deleted_client na conta conectada | a conexão foi revogada ou o cliente OAuth foi apagado | Reconectar o Gmail |
Outros erros estão em Solução de problemas.