Contents
- Overview
- Step 1: Create a service account in Google Cloud
- Step 2: Authorize domain-wide delegation
- Step 3: Enroll the credential in the backup client
- Step 4: Verify the credential
- Step 5: Choose what to back up
- Step 6: Run the backup
- Step 7: Restoring
- What is covered, and what is not
- Troubleshooting
Backing up Google Workspace with WholesaleBackup
Welcome to WholesaleBackup's guide to protecting Google Workspace. Your backup client can back up and restore Gmail, contacts, calendars, Google Drive and shared drives straight from a customer's Google Workspace domain, alongside the files and folders it already protects. Let's get started!
Why back up Google Workspace at all?
Google keeps your customer's data highly available. It does not keep it recoverable. Trash empties itself after 30 days, a departing employee's account and everything in it goes when the account is deleted, and ransomware syncing through Drive for desktop or a disgruntled administrator can destroy a year of work as easily as a file share.
WholesaleBackup keeps its own copy, outside Google:
-
Gmail is stored as the original message, byte for byte, so it goes back into Gmail exactly as it arrived, or comes out as a portable
.emlfile that opens in any mail program without any WholesaleBackup software at all. - Drive files are stored as files. Google Docs, Sheets and Slides are saved as Word, Excel and PowerPoint, so they open on any computer.
- Contacts and calendars are stored in Google's own format, and go back into the account they came from.
What you need before you start
-
A Google Workspace domain, and a super administrator of it, or an administrator who can manage domain-wide delegation and a Google Cloud project for it. Personal
@gmail.comaccounts are not supported: they have no administrator and no domain-wide delegation. - Your backup client already installed and running backups successfully. Google Workspace is an additional source, not a separate product.
- The build password for the client GUI, which protects the credential page.
Setup runs once per domain and takes about twenty minutes.
Step 1: Create a service account in Google Cloud
WholesaleBackup reaches Google Workspace through a service account in a Google Cloud project that belongs to the customer's organization. Nobody signs in and no user password is involved: the service account proves who it is with a key, and acts on each mailbox through domain-wide delegation, which is what lets an unattended backup run at 2 a.m.
- Sign in to console.cloud.google.com as an administrator of the customer's organization.
- Create a project, or pick one. It must have the customer's organization as its parent. Name it something a future administrator will recognize, such as
WholesaleBackup. - Under APIs & Services, enable the Gmail API and the Admin SDK API. Also enable the People API, Google Calendar API and Google Drive API if you will back up contacts, calendars or Drive files.
- Go to IAM & Admin → Service accounts and click Create service account. Give it a name and leave the project roles empty: its access comes from domain-wide delegation in Step 2, not from the project.
- Open the service account, go to Keys → Add key → Create new key, choose JSON, and click Create. A key file downloads.
- On the service account's Details tab, copy its numeric Unique ID. This is its client ID, and Step 2 needs that number, not the account's email address.
The key file is shown once: Google keeps only the public half. Keep it somewhere secure until Step 3, then delete the download.
If the console will not create a key
Organizations created recently have service-account key creation turned off by policy (iam.managed.disableServiceAccountKeyCreation and iam.disableServiceAccountKeyUpload). Turning them off needs the Organization Policy Administrator role, which the Organization Administrator role does not include, so it has to be granted at the organization level first. Creating a project at all needs resourcemanager.projects.create, which Organization Administrator does not include either.
Step 2: Authorize domain-wide delegation
Domain-wide delegation is what allows the service account to read each user's mail, contacts, calendars and Drive. You grant it in the Google Admin console, not the Cloud console.
- Sign in to admin.google.com as a super administrator.
- Go to Security → Access and data control → API controls, then click Manage domain-wide delegation.
- Click Add new and paste the service account's numeric client ID from Step 1.
- Paste the scopes below into OAuth scopes as one comma-separated list, and click Authorize.
Backup scopes (read-only)
| Scope | Needed to |
|---|---|
https://www.googleapis.com/auth/gmail.readonly |
read each mailbox |
https://www.googleapis.com/auth/admin.directory.user.readonly |
list the domain's users |
https://www.googleapis.com/auth/admin.directory.group.readonly |
find a member to read a shared drive as, when it is shared through a group |
https://www.googleapis.com/auth/contacts.readonly |
read each user's contacts |
https://www.googleapis.com/auth/calendar.readonly |
read each user's calendars |
https://www.googleapis.com/auth/drive.readonly |
read Drive files and list shared drives |
Restore scopes (write)
| Scope | Needed to |
|---|---|
https://www.googleapis.com/auth/gmail.readonly |
resolve the mailbox being restored into |
https://www.googleapis.com/auth/gmail.insert |
put messages back into a mailbox |
https://www.googleapis.com/auth/gmail.labels |
create the restore label |
https://www.googleapis.com/auth/contacts |
create restored contacts |
https://www.googleapis.com/auth/calendar |
create the calendar a restore writes into |
https://www.googleapis.com/auth/drive.file |
create restored files in Drive. It can touch only files the restore itself created, never anything else in the user's Drive |
Every scope in the list is required
⚠️ The backup client always asks Google for the whole list, even for a customer who only backs up mail, and Google refuses the request outright if the delegation entry is missing any one of them. A single missing scope does not just stop that service: it stops every Google service for that domain, Gmail included, until the entry is fixed. Copy the list exactly.
Three things are easy to get wrong:
- The scope box replaces; it does not add. When you edit an existing entry, paste the whole list again. Leaving out a scope that was there before breaks backups.
-
A
.readonlyscope is not covered by its read-write sibling. An entry withcontactsbut notcontacts.readonlyfails the backup credential. - Changes take a few minutes to reach Google's sign-in servers. A permission error immediately after saving usually means "wait", not "wrong".
Should you use one service account or two?
Two is the safer arrangement, and it is what we recommend. Create a second service account for restore, give its delegation entry only the restore scopes, and keep the backup service account read-only.
The reason is the same as for any backup: backups run unattended every night, while restores are rare and deliberate. If the key in routine use cannot write to a mailbox, then no bug, no misconfiguration and no attacker who obtains that key can alter a customer's mail through it.
Using one service account for both
You can use one service account, enroll it once with both Backup and Restore ticked, and it works. Google keeps one delegation entry per client ID, so that one entry must carry both lists. Paste this into its scope box:
https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/contacts.readonly,https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/gmail.insert,https://www.googleapis.com/auth/gmail.labels,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/contacts,https://www.googleapis.com/auth/drive.file
What you give up is the guarantee above: the key in nightly use is then permitted to write into every mailbox and Drive in the domain.
Step 3: Enroll the credential in the backup client
On the machine running the backup client, open the client GUI and browse to the /cloud page, then choose Google Workspace. By default the GUI listens at https://client.backupops.com:3443, so the page is at https://client.backupops.com:3443/cloud/google-workspace.
⚠️ This page is reached by URL only and is not in the navigation menu, the same as the /host page. It asks for the build password before it will show anything.
Fill in Add or replace a service account:
| Field | What to enter |
|---|---|
| Workspace domain | The customer's primary domain, e.g. contoso.com. This is what the selections tree will show. |
| Administrator to list mailboxes as | The email address of a person who is an administrator in that domain, e.g. it-admin@contoso.com. Google lists a domain's users only to an administrator, so the backup client acts as this person for that one purpose. It cannot be the service account itself. |
| Service account key (JSON) | Open the key file from Step 1 in a text editor and paste the whole file, as-is. |
| Use this credential for | Tick Backup, Restore, or both. |
If you created two service accounts, enroll them one at a time: the backup one with Backup ticked, the restore one with Restore ticked.
Click Enroll. The credential appears in the enrolled list above the form, and you can delete the downloaded key file.
How the key is stored
The service account key is never stored in plain text. It is encrypted into a key file beside the backup client's configuration, tied to that installation, and decrypted only inside the short-lived process that talks to Google, never by the always-on service that serves this page. It is never written to a log, never shown again once entered, and never passed on a command line.
The enrolled list shows the domain, the service account, the administrator it lists mailboxes as, what it is used for, and whether a key is stored. To replace a key, when you rotate it for instance, enroll the same domain again with the new key and it replaces the old one.
A computer can hold credentials for more than one Google Workspace domain, and for Microsoft 365 as well.
Step 4: Verify the credential
Click Check permissions beside the credential you just enrolled.
This is not a local check. It signs in to Google as the administrator you named, with the full scope list, which is the only way to be certain the delegation entry is right. Do this before you configure selections, not after the first backup fails.
| Result | What it means |
|---|---|
| Google signed in as … | Domain-wide delegation covers every scope this credential uses. You are ready. |
| Google knows … but its domain-wide delegation entry does not include every scope | The entry exists but is missing at least one scope. The message lists every scope the entry must include: paste the whole list again (Step 2). |
| Google has not authorised … for these scopes | There is no delegation entry for this client ID, or it is for a different one. Check you pasted the numeric Unique ID, not the email address. |
| Google refused the sign-in as … | The administrator you named is not an active user of the domain, the key has been deleted or disabled, or this computer's clock is wrong. |
| Google does not recognise … or its key | The key was deleted in the Cloud console. Create a new key and enroll again. |
| This credential was enrolled before some of the scopes it needs were added | The credential was enrolled by an older version of the client. Enroll the same domain again with the same key. |
If you have only just saved the delegation entry, wait a few minutes and check again before changing anything.
Step 5: Choose what to back up
Go to Backup → Selections. A Cloud Services branch now sits beside Computer and Network. If you do not see it, no credential is enrolled on this machine: go back to Step 3.
Expand it and the tree fills in as you go:
-
Cloud Services
-
Google Workspace
-
contoso.com, the domain
-
Joe Smith, a user
- Contacts
- Calendars
- Drive
- Amy Jones, a user
- Shared drives
-
Joe Smith, a user
-
contoso.com, the domain
-
Google Workspace
Tick Mail, Contacts, Calendars and Drive for each user you are protecting, and each shared drive you want under Shared drives.
Users are chosen one by one
There is no "all users" selection for Google Workspace. When the customer adds a new employee, add their mailbox to the selections, or it will not be backed up. Removing a user from the selections does not delete what was already backed up: it ages away under your retention setting.
What each selection covers
| Selection | Covers |
|---|---|
| The whole mailbox, every label, including Trash, because mail the customer deleted is usually the reason they restore. Spam is left out unless you turn it on (below). | |
| Contacts | The user's address book. Google gives one per user. |
| Calendars | The calendars the user owns. Subscribed calendars, holidays, birthdays and calendars other people share with them are skipped, because their owner's backup covers them. |
| Drive | The files the user owns, in My Drive and in other people's folders. Expand it to choose or exclude folders. Files shared with the user are backed up from their owner, once. |
| A shared drive | The whole shared drive. Its folders cannot be chosen one by one yet. |
Gmail is backed up whole: labels cannot be selected or excluded one by one.
Excluding a Drive folder
Tick Drive, expand it, and untick a folder inside it to exclude it. An exclusion covers everything beneath that folder.
Backing up Spam
Spam is not backed up by default. To include it, turn on Back up Spam under Backup options on the Google Workspace credentials page. While it is off, a message the user marks "Not spam" is backed up on the next run, and spam backed up earlier ages away under your retention setting.
Step 6: Run the backup
Google Workspace items back up as part of the ordinary backup. There is no separate schedule, no separate job, and nothing extra to start. Run a backup as you always would, or wait for the schedule.
What to expect on the first run
The first backup downloads everything in the selection, so it takes far longer than later ones. Mail downloads several mailboxes in parallel. Google throttles busy accounts, and the client handles that by waiting and retrying rather than failing.
Drive is deliberately paced. To stay within Google's daily download limit, each Google Workspace domain downloads at most about 900 GB of Drive files per day. A large Drive takes several days to complete its first backup, and the log says so:
today's download budget for this Google account is used up (D8); the rest continues tomorrow
Every run after the first only fetches what changed. On a large mailbox, each run still spends a few minutes checking every label for changes before it starts, which is normal.
Reading the log
The backup log reports one line per mailbox, address book, calendar set and drive, for example:
Gmail [joe@contoso.com]: 178197 message(s) of 4.16 GB selected; 9 new, 0 newly deleted this run Google calendar [joe@contoso.com]: 6 calendar(s), 385 event(s) of 463 KB selected; 0 new or changed, 0 newly deleted this run
You will also see lines naming what was deliberately left out:
Gmail [joe@contoso.com]: 81 spam message(s) left out (spam is not backed up) Google calendar [joe@contoso.com]: 1 calendar(s) the user does not own were skipped (subscribed feeds, holidays, calendars shared with them). Name one explicitly to back it up anyway.
That is information, not an error.
If a listing cannot be completed, from a network drop or a permission problem, the log says so and adds "NO deletions are inferred". The client never concludes that items are gone from a listing it could not finish.
Deleted items are kept
When an item disappears from Google, the client marks it deleted in its catalog rather than discarding it. It stays restorable until your retention setting ages it out. A message moved to Gmail's Trash is still backed up and is not treated as deleted. A Drive file moved to Drive's Trash is treated as deleted, and is kept for your retention period.
When a Drive file changes, the earlier version the client stored is kept too, and ages away under the same retention setting.
Step 7: Restoring
Go to Restore, and choose what to restore in the Restore selector at the top of the page: Google Workspace mail, Google Workspace contacts, Google Workspace calendars, Google Drive or Google shared drives. Each appears only when this computer holds a backup of that kind.
The page lists what was backed up, not what is in the account now.
Restoring mail
- Pick the mailbox.
- Set Show to Everything backed up, Still in the mailbox, or Deleted from the mailbox. The last is the one to reach for when someone has lost something.
- Pick a label on the left, or leave Whole mailbox.
- Tick individual messages, or leave everything unticked to restore the whole label.
Ticked messages win: if you tick four messages while looking at a label of nine hundred, you get the four. Then choose where it goes:
| Destination | What happens |
|---|---|
| Files on this computer | One .eml per message, written to a folder you name. Opens in Outlook or any mail program. Nothing in Google Workspace is touched. |
| Back into the mailbox | Each message goes back into the mailbox it was backed up from, exactly as it was stored, with its original date, under a new label. |
Where restored mail appears
A mailbox restore creates a new label, named Restore 2026-11-05 14.22.01 by default, and never alters, overwrites or merges into anything already in the mailbox. Look for it in the label list in Gmail's left-hand menu.
- The message's own labels are recreated beneath the restore label, as
Restore 2026-11-05 14.22.01/Clients/Acme, so nothing restored mixes into the user's live labels. - Unread and starred are put back as they were.
- Restored mail does not reappear in the Inbox, Sent or Gmail's category tabs. Find it under the restore label.
Restoring contacts and calendars
Pick the user, tick items or leave them all unticked for everything, and restore. Contacts and calendars restore into the account only: there is no file form for them.
| Restoring | What you get |
|---|---|
| Contacts |
New contacts, grouped under a new label named Restore …. Deleting the label afterwards does not delete the contacts: each has to be removed individually. Contact photos and the contacts' original labels are not restored. |
| Calendars | A new calendar named Restore …, holding the restored events from all the user's calendars. Deleting that calendar removes all of it. The restoring user becomes the organizer of restored events. A cancelled event is not re-created: a cancellation records that something was deleted, not an event to put back. |
If you restored a calendar and cannot find it, look in the calendar list on the left of Google Calendar, under "My calendars".
Restoring Drive files
- Pick the user, or the shared drive, and browse to the files or folders you need.
- Under Version, choose a date to restore files as they were then, or the latest version.
| Destination | What happens |
|---|---|
| Files on this computer | Files are written to a folder you name, in their Drive folder structure. Google Docs, Sheets and Slides come back as Word, Excel and PowerPoint. Nothing is overwritten: a name already taken gets " (2)", and a name Windows cannot use is changed. A file named _divinsa_restore_manifest.csv beside them lists every file and anything renamed. |
| Back into Google Drive | Everything goes into a new folder, Restore …, at the top of the user's My Drive, or of the shared drive. Google Docs, Sheets and Slides are converted back into Google files. Restored files are shared with no one. You can restore one user's files into another user's My Drive; a shared drive restores into itself. |
While it runs
Starting a restore switches you to the Overview page, the same as a file restore. A cloud restore appears in Details with its item counts and its own log, alongside every other operation.
Nothing is deleted from Google and nothing existing is changed: a restore only ever adds.
What is covered, and what is not
| Item kind | Backs up | Restores into Google | Restores as files |
|---|---|---|---|
| Gmail | Yes, including Trash. Spam if turned on | Yes | Yes, .eml
|
| Contacts | Yes | Yes, as new contacts | No |
| Calendars the user owns | Yes | Yes, into a new calendar | No |
| Drive files the user owns | Yes | Yes | Yes |
| Shared drives | Yes, whole drives | Yes, into the same drive | Yes |
| Google Docs, Sheets, Slides | Yes, as Word, Excel, PowerPoint | Yes, converted back | Yes, as Office files |
| Google Drawings, Apps Script | Yes, as .svg and .json
|
As .svg and .json files |
Yes |
| Google Forms, Sites, My Maps, Jamboards, Vids | No: Google offers no way to export them | No | No |
| Drive shortcuts | No: the file it points to is backed up from its owner | No | No |
| Subscribed and shared calendars | Only if named explicitly | ||
| Google Chat, Keep, Tasks | No | No | No |
A note on Google Docs
Google Docs, Sheets and Slides have no file of their own, so they are saved in Office format. Their content comes back, but comments, suggestions, Google's own version history and sharing settings do not. If a Drive file's owner has turned off downloading, Google refuses to give the file to anyone, and the log reports it as download-refused until downloading is turned back on.
Retention
Google Workspace items follow the same retention setting as everything else the client backs up. An item deleted from Google stays restorable until your retention window passes, then ages out with the rest.
Troubleshooting
The Cloud Services branch is missing from Selections
No credential is enrolled on this machine. Go to /cloud/google-workspace and enroll one (Step 3).
The domain shows no users in Selections
The credential names no administrator to list mailboxes as, or the delegation entry is missing admin.directory.user.readonly. Enroll the domain again naming an administrator, and click Check permissions.
Every Google service fails with "Requested client not authorized"
The delegation entry is missing at least one scope this credential asks for. Google then refuses the credential altogether, so mail, contacts, calendars and Drive all fail together, and nothing is wrongly deleted ("NO deletions are inferred"). The log names the fix once per run:
Google sign-in refused for [it-admin@contoso.com]: Google knows wsbu-backup@contoso-backup.iam.gserviceaccount.com, but its domain-wide delegation entry does not include every scope this credential asks for. In the Admin console, under Security > API controls > Domain-wide delegation, edit its entry so it includes all of: ...
Paste the full list from Step 2 into the entry again, wait a few minutes, and click Check permissions. The usual cause is an entry that was edited to add some scopes and lost others, because the scope box replaces rather than adds.
"Check permissions" fails right after I set up delegation
Google can take a few minutes to apply a delegation change. Wait, and check again before changing anything.
"Google refused the sign-in as …"
The administrator named on the credential has been suspended, deleted or renamed, the key was disabled in the Cloud console, or this computer's clock is wrong. Enroll the domain again naming an active administrator, or with a new key.
A shared drive is skipped with "has no member this backup can read it as"
Google lets only a shared drive's members read it, and the client found none it could act as. Add the administrator named on the credential, or any active user of the domain, as a member of the shared drive.
Some Drive files are "not fetchable"
These are Google Forms, Sites, My Maps, Jamboards and Vids, which Google offers no way to export, and shortcuts, whose target is backed up from its owner's Drive. This is reported as information, not as an error.
A calendar a user sees every day was not backed up
Only calendars the user owns are backed up. A calendar someone else owns is backed up from the owner's account, if they are selected. Subscribed feeds and holidays are not backed up at all.
A restore says nothing was restored, or to enroll the restore credential
No credential with Restore ticked is enrolled for that domain, or its delegation entry lacks the restore scopes. Enroll the restore credential (Step 3) and click Check permissions.
I restored mail and cannot find it in the Inbox
Restored mail goes under its restore label, not the Inbox. Look in the label list in Gmail's left-hand menu, under Restore ….
"The engine is busy"
A backup or another restore is running. The client runs one engine at a time by design. Wait for it to finish and try again.
Still stuck?
The backup log names the user, service and item for every decision it makes, and the restore log names the account items went back into. Send the relevant log to support@wholesalebackup.com and we will take a look.
If you find anything in this guide unclear, please send your questions, comments and feedback to support@wholesalebackup.com and we will revise the guide accordingly.