# Google Workspace: connecting mailboxes

For the assistant to read mail in Google Workspace and write drafts there, it
needs access through the Gmail API. There are two routes, and both rest on
what the organisation sets up in **its own Google Cloud**. draften has no
shared app you would simply consent to. This holds for our service and for an
installation on your own server alike.

We count on **Google Workspace**. Personal `@gmail.com` accounts are not
supported: they cannot sign in to draften, and connecting them would require
the app to be verified by Google.

## Which route to choose

| | For the whole organisation | With the mailbox account |
|---|---|---|
| In draften | a registration (service account) in Organisation → **Integrations** | the **Connect Gmail** button at the mailbox |
| At Google | a service account with a key and domain-wide delegation | an OAuth client and a consent screen of the Internal type |
| Who sets it up | a Google Cloud administrator and a Google Admin super administrator | a Google Cloud administrator |
| Who has to sign in | nobody | the owner of each mailbox, once |
| Which mailboxes it reaches | every mailbox of the domain | only the mailbox whose account signed in |
| Signing in to draften with a Google account | no, that is a separate matter | the same OAuth client serves sign-in too |

For an organisation with several mailboxes, the **route for the whole
organisation** is simpler. **With the mailbox account** suits you when you do
not want to give one key access to every mailbox of the domain, or when you
are introducing signing in with Google accounts anyway.

You can have both routes at once; each mailbox uses one of them. draften asks
only for the `gmail.modify` scope — reading and creating drafts; it sends
nothing.

## Route A: for the whole organisation

### In Google Cloud

You work in https://console.cloud.google.com, in the organisation of your
Workspace domain.

1. Choose a project, or create a new one (say `draften`).
2. **APIs & Services** → **Library** → **Gmail API** → **Enable**.
3. **IAM & Admin** → **Service accounts** → **Create service account**. A
   name, say `draften-mail`. It needs no roles in the project — its access to
   mail comes from the delegation in Google Admin. Click **Done**.
4. Open the service account and note down its **Unique ID** — the numeric
   Client ID.
5. The **Keys** tab → **Add key** → **Create new key** → **JSON** →
   **Create**. A file with the key is downloaded.

!> If Google refuses to create the key, your organisation has the
`iam.disableServiceAccountKeyCreation` policy on (new organisations have it
on by default). An organisation administrator turns it off for this project
in **IAM & Admin** → **Organization policies**.

### In Google Admin

You need a super administrator. In https://admin.google.com open
**Security** → **Access and data control** → **API controls** → **Manage
Domain Wide Delegation** → **Add new**. **Client ID**: the numeric ID from
step 4. **OAuth scopes**: `https://www.googleapis.com/auth/gmail.modify`.
Click **Authorize**. The delegation usually takes effect within a few
minutes, exceptionally only after several hours.

### In draften

1. Open Organisation → **Integrations**, the **Organisation-wide mail access**
   card. Registrations are managed by the organisation's owner or managers.
2. **System**: **Google Workspace**. Fill in **Name**, choose the downloaded
   file under **Service account key (JSON)** and click **Add registration**.
   The key is stored encrypted; the card then shows only the service
   account's e-mail and its Client ID.
3. On each mailbox's page, in the **Mail access** card, choose this
   registration under **Use**, click **Apply** and then **Test the
   connection**. The procedure with screenshots is in the guide [Adding and
   connecting a mailbox](/en/admin/adding-a-mailbox).

**Then delete the downloaded key file.** Whoever has it gets into every
mailbox of the domain. You upload a new key of the same service account at
the registration with **new key (JSON)**; add a key of another service
account as a new registration. Delete the old key in Google Cloud.

With **Mailbox automatically** on ([How members sign
in](/en/admin/member-sign-in)), a new mailbox is bound to the registration by
itself when exactly one is active for Google Workspace.

## Route B: with the mailbox account (Connect Gmail)

Here the mailbox owner signs in with their Google account and allows access
to their own mail only. The same OAuth client also serves **signing in to
draften with a Google account**.

### In Google Cloud

1. In draften, first open Organisation → **How members sign in**, the
   **Account sign-in and mailbox connections** card. It shows two **redirect
   URIs** made exactly for your draften address — ending in
   `/auth/google/callback` and `/mailboxes/connect/google/callback`. Copy them
   from there; they must match character for character.
2. In the project with the **Gmail API** enabled (step 2 of route A), open
   **APIs & Services** → **OAuth consent screen**. **User type**:
   **Internal** — only accounts of your domain can then sign in, and the app
   does not have to be verified by Google. Fill in the app name (say
   `draften`) and a contact e-mail.
3. In the scopes part (**Scopes** / **Data access**), add `openid`,
   `email`, `profile` and `https://www.googleapis.com/auth/gmail.modify`.
4. **APIs & Services** → **Credentials** → **Create credentials** → **OAuth
   client ID**. **Application type**: **Web application**. Put both addresses
   from the card into **Authorized redirect URIs** and click **Create**.
5. Copy the **Client ID** and the **Client secret**.

### In draften

1. The **organisation owner** fills in the **Client ID** and the **Client
   secret** under **Google OAuth client** in the **Account sign-in and
   mailbox connections** card and clicks **Save**.
2. The **mailbox owner** opens the mailbox's page and clicks **Connect
   Gmail** in the **Mail access** card. They sign in **with that mailbox's
   account** — draften refuses any other — and allow the access. Only the
   mailbox owner sees the button, and only when the organisation has the
   OAuth client.
3. Then **Test the connection**.

You switch on **signing in with a Google account** on the same page: write
your Workspace domain into **The organisation's e-mail domains** — the
primary one, not an alias domain (Google does not send that at sign-in). Once
the organisation has both the OAuth client and the domain, members sign in
with their Google accounts and their passwords stop working — see [How
members sign in](/en/admin/member-sign-in).

### When a mailbox disconnects

- **The account was deleted or blocked, or the access revoked** — Google
  stops issuing tokens and draften disconnects the mailbox. Connect it again
  (**Reconnect Gmail**), or through route A.
- **"The provider issued no refresh token"** — the mailbox owner removes the
  app in their Google account settings (**Security** → **Third-party apps**)
  and connects the mailbox again.
- **"A different account signed in than the mailbox address"** — when
  connecting, pick the account of exactly that mailbox.

## Connection test errors

The test checks three steps: **Access**, **Token and permission** and
**Reading the Inbox**.

| In the message | What it means | What to do |
|---|---|---|
| delegation for the scope is not allowed (`unauthorized_client`) | domain-wide delegation is missing in Google Admin, or it has another Client ID or scope | check the delegation in Google Admin: the numeric ID and the exact `gmail.modify` scope |
| `invalid_grant` with a service account | there is no such mailbox in the Workspace domain | check the mailbox address |
| "Gmail API has not been used…" | the Gmail API is not enabled in the project | enable the Gmail API (step 2) |
| a token without `gmail.modify` | the delegation or the consent screen lacks the `gmail.modify` scope | add the scope |
| `invalid_grant`, `deleted_client` with a connected account | the connection was revoked or the OAuth client deleted | **Reconnect Gmail** |

Other errors are covered in [Troubleshooting](/en/admin/troubleshooting).