# Google Workspace: conectar caixas de e-mail

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.

1. Escolha um projeto ou crie um novo (por exemplo `draften`).
2. **APIs & Services** → **Library** → **Gmail API** → **Enable**.
3. **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**.
4. Abra a conta de serviço e anote o **Unique ID** dela – o Client ID numérico.
5. 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

1. 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.
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 **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](/pt/admin/adding-a-mailbox).

**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](/pt/admin/member-sign-in)), 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

1. 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/callback` e `/mailboxes/connect/google/callback`. Copie-as de
   lá; elas precisam coincidir caractere por caractere.
2. 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.
3. Na parte dos escopos (**Scopes** / **Data access**), adicione `openid`,
   `email`, `profile` e `https://www.googleapis.com/auth/gmail.modify`.
4. **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**.
5. Copie o **Client ID** e o **Client secret**.

### No draften

1. 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**.
2. 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.
3. 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](/pt/admin/member-sign-in).

### 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](/pt/admin/troubleshooting).