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 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.

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), 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.

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.

Other errors are covered in Troubleshooting.