For administrators
← All topics

Google Workspace: connecting mailboxes

Connecting with the mailbox account (organisation client), and a service account on top for shared mailboxes — and what to set up in Google Cloud and Google Admin, step by step.

For the assistant to read mail in Google Workspace and write drafts there, it needs access through the Gmail API. For that, the organisation sets something 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.

Everything here applies only to Google Workspace accounts with their own domain. You cannot sign in to draften with a personal @gmail.com account; you can, however, connect a personal Gmail over IMAP with an app password — see Supported providers and their limits.

What you want and what to set up

What you wantWhat to set up
Members sign in with a Google account and each has their own mailboxthe organisation client — that is enough
On top of that, mailboxes nobody signs in to (say info@), or mailbox access set up centrally, without their ownersthe organisation registration (a service account) as well
You do not want signing in with Google accountspeople sign in with the password from their invitation; the organisation registration (or IMAP) connects the mail

Two separate things at Google

The organisation client and the organisation registration are two separate things in Google Cloud. Each does something different, and neither can stand in for the other:

Organisation clientOrganisation registration
What it isan OAuth client with a consent screen of the Internal typea service account with a key and domain-wide delegation
What it doesmembers signing in with the Sign in with Google button, and the Connect Gmail button at a person's own mailboxthe assistant's access to mailboxes without their owners signing in
Where in draftenOrganisation → Sign-in and mail access → the Account sign-in and mailbox connections cardOrganisation → Sign-in and mail access → the Registrations for shared mailboxes and central management card
Who sets it up in draftenthe organisation ownerthe organisation's owner or a manager
Who creates it at Googlea Google Cloud administratora Google Cloud administrator and a Google Admin super administrator
Who signs in to the mailboxthe owner of each mailbox, oncenobody
Which mailboxes it reachesonly those that people connect themselvesevery mailbox of the domain

They are two things on purpose. Consent to the client grants rights only to the mailboxes that people connect themselves — never to the mail of the whole domain. The service account, on the other hand, reaches every mailbox of the domain, and that is why only draften gets it, for mailbox access, not for signing in. Do not merge them.

Each mailbox uses one of the two kinds of access; you can have both at once. draften asks only for the gmail.modify scope — reading and creating drafts; it sends nothing.

Organisation client: signing in and Connect Gmail

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

In Google Cloud

You work in https://console.cloud.google.com, signed in with an administrator account of your Workspace domain. Everything happens in one project — the selected project is shown at the top left, next to the Google Cloud logo; that is also where you switch it or create a new one. Open the main menu with the ☰ icon at the top left.

  1. In draften, first open Organisation → Sign-in and mail access, 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. Choose a project, or create a new one (say draften), and enable the Gmail API in it: ☰ → APIs & Services → Library, search for Gmail API, open it and click Enable. Directly: https://console.cloud.google.com/apis/library/gmail.googleapis.com
  3. Set up how the app presents itself to users (the consent screen): ☰ → APIs & Services → OAuth consent screen. The Google Auth Platform page opens; directly: https://console.cloud.google.com/auth/overview (check that the right project is selected at the top). Click Get started and go through the wizard:
    • App Information — App name draften and User support email (your e-mail or an administrators' group). Next.
    • Audience — choose Internal. Only accounts of your Workspace domain can then sign in, and the app does not have to be verified by Google. Next.
    • Contact Information — the e-mail to which Google sends you notices about the app. Next.
    • Finish — tick the box agreeing to Google's policy (I agree to the Google API Services: User Data Policy), click Continue and then Create.
  4. Allow the app its scopes. In Google Auth Platform, open Data Access in the menu on the left (directly: https://console.cloud.google.com/auth/scopes) → Add or remove scopes. In the list, tick openid, .../auth/userinfo.email and .../auth/userinfo.profile. Paste the Gmail scope into the Manually add scopes field: https://www.googleapis.com/auth/gmail.modify → Add to table. Click Update and then Save at the bottom.
  5. Create the client. In Google Auth Platform, open Clients in the menu on the left (directly: https://console.cloud.google.com/auth/clients) → Create client. Application type: Web application, a name say draften. Under Authorized redirect URIs, click Add URI and paste the first address from the card, then Add URI again and the second one. Click Create.
  6. The Client ID and the Client secret are shown — copy both straight away. Google does not show the Client secret again later; if you lose it, create a new one at the client.

In draften

  1. The organisation owner opens Organisation → Sign-in and mail access and, in the Account sign-in and mailbox connections card, fills in the Client ID and the Client secret from step 6 under Google OAuth client, then clicks Save.
  2. They switch on signing in with a Google account on the same page, in the How members sign in card: they write their 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 client and the domain, members sign in with their Google accounts and their passwords stop working — see How members sign in.
  3. The mailbox owner opens the mailbox's page and, in the Mail access card, in the Connect with the mailbox account: row, clicks Connect Gmail. 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 client; without it, the card says instead of the button that connecting with an account will work once the organisation owner adds the client.
  4. Then Test the connection.

When a mailbox disconnects

Organisation registration: access without signing in

A service account with domain-wide delegation gives the assistant access to the domain's mailboxes without anyone signing in. It suits mailboxes nobody signs in to (say info@) and organisations that want to manage access centrally. It has nothing to do with signing in to draften.

In Google Cloud

You work in https://console.cloud.google.com, in the same project where the Gmail API is enabled (step 2 of the organisation client; without a client, enable it the same way). Check the project at the top left, next to the Google Cloud logo.

  1. Open the list of service accounts: ☰ → IAM & Admin → Service accounts. Directly: https://console.cloud.google.com/iam-admin/serviceaccounts
  2. At the top, click + Create service account and go through three steps:
    • Service account details — Service account name say draften-mail (the ID fills in by itself). Click Create and continue.
    • Permissions (optional) — choose nothing; it needs no roles in the project, its access to mail comes from the delegation in Google Admin. Click Continue.
    • Principals with access (optional) — fill in nothing, click Done.
  3. In the list, click the new service account. On the Details tab, copy the Unique ID — a long number; that is the Client ID for Google Admin.
  4. The Keys tab → Add key → Create new key → Key type: JSON → Create. The browser downloads a file with the key (….json).

If Google refuses to create the key, your organisation has the Disable service account key creation policy switched on (iam.disableServiceAccountKeyCreation; new organisations have it on by default). An organisation administrator turns it off for this project: ☰ → IAM & Admin → Organization policies (https://console.cloud.google.com/iam-admin/orgpolicies), searches for iam.disableServiceAccountKeyCreation → Manage policy → Override parent's policy → Enforcement: Off → Set policy. Then repeat step 4.

In Google Admin

You need a Google Workspace super administrator account.

  1. Open https://admin.google.com → in the menu on the left Security → Access and data control → API controls → at the bottom Domain wide delegation → Manage domain wide delegation. Directly: https://admin.google.com/ac/owl/domainwidedelegation
  2. Click Add new and fill in:
    • Client ID — the numeric Unique ID from step 3,
    • OAuth scopes (comma-delimited) — https://www.googleapis.com/auth/gmail.modify.

    Click Authorize. The delegation appears in the list. It usually takes effect within a few minutes, exceptionally only after several hours.

In draften

  1. Open Organisation → Sign-in and mail access, the Registrations for shared mailboxes and central management 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 Organisation registration, 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 (step 4 above) at the registration with new key (JSON); add a key of another service account as a new registration. Then delete the old key in Google Cloud: the service account → the Keys tab → the bin icon at the old key.

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.

Connection test errors

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

In the messageWhat it meansWhat 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 scopecheck the delegation in Google Admin: the numeric ID and the exact gmail.modify scope
invalid_grant with a service accountthere is no such mailbox in the Workspace domaincheck the mailbox address
"Gmail API has not been used…"the Gmail API is not enabled in the projectenable the Gmail API
a token without gmail.modifythe delegation or the consent screen lacks the gmail.modify scopeadd the scope
invalid_grant, deleted_client with a connected accountthe connection was revoked or the client deletedReconnect Gmail

Other errors are covered in Troubleshooting.

Plain text version