Connect a Google Workspace mailbox

View as Markdown Open in ChatGPT Open in Claude

Connect a Google Workspace mailbox so the mail sent to it becomes tickets and your replies go out from it. When you finish, Outpost reads and sends as that one mailbox, and no password is stored. For how email becomes tickets, see Email to ticket.

The recommended method is Google Workspace domain-wide delegation. A Google Workspace super admin authorizes Outpost once in the Admin console, and you prove you control the domain with a DNS record. Outpost asks Google for a short-lived token for the one mailbox each time it needs one.

A personal Gmail account (an @gmail.com address) cannot use domain-wide delegation. Connect it with an app password instead. See Connect a mailbox with IMAP.

Before you begin

You need mailbox:manage in the console.
You need a Google Workspace super admin to add the authorization.
You need to be able to add a TXT record to the domain’s DNS.
Remote Outpost cannot connect to Google Workspace. Use IMAP there.

Domain-wide delegation applies to the whole Google Workspace domain: Google lets Outpost act as any user in the domain with the two scopes you grant. Outpost only ever asks for a token for a mailbox you have connected, and only for a domain whose DNS record proves that your organization controls it.

Connect with domain-wide delegation

In the console, go to Settings > Mailboxes and select Add mailbox.
In Support address, enter the address, such as [email protected], and select Continue.
The wizard shows Looks like Google Workspace. Choose Google Workspace domain-wide delegation and select Continue.

The wizard shows the Client ID and the Scopes, each with a copy button. The scopes are:

https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/gmail.send

Select Open domain-wide delegation, or in the Google Admin console go to Security > Access and data control > API controls > Manage domain-wide delegation.
Select Add new. Paste the client ID and the scopes from the wizard, then select Authorize.
Back in the wizard, under Prove you own your domain, copy the TXT record’s Name and Value. Add the record at your DNS host. The name is _outpost-mail. followed by your domain, and the value starts with outpost-mail=.
Select Check the DNS record. When the record is found, the wizard shows Domain verified. DNS can take a while to update, so if it shows Not verified yet, wait and check again.
Select Test it. See Verify.
In the Routing step, choose where new tickets land, then select Save mailbox.

You authorize Outpost and prove the domain once per domain. For a second mailbox in the same domain, the wizard shows Domain verified straight away, and you select Test it.

Connect with your own service account

Use this when you want the authorization to belong to a service account in your own Google Cloud project.

In your Google Cloud project, create a service account and download a JSON key for it.
In the Google Admin console, under Manage domain-wide delegation, add the service account’s client ID with the two scopes above.
In the wizard, under Advanced, choose Your own Google service account and select Continue.
In Service account key (JSON), choose the key file.
Select Save and test.

Outpost stores the key encrypted and never shows it again. To replace it, select Reconnect on the mailbox’s row and choose a new file.

The wizard offers Sign in with Google when it is available on your Outpost. It signs in as the mailbox itself, with no Admin console step. When it is not offered, use domain-wide delegation.

Verify

The test runs Connect, Sign in, Send a test message, and Receive the test message, in order, and stops at the first that fails. Access limited to this mailbox shows Skipped: it applies to Microsoft 365 only. The test message is never turned into a ticket.

In Settings > Mailboxes, the mailbox shows Connected. Send a message to the support address from another account. A ticket appears in the mailbox’s queue, and the message is marked as read in Gmail.

If something goes wrong

Message	Cause	Fix
Google has not authorized Outpost for this domain.	The client ID or scopes are missing or mistyped in the Admin console, or Google has not applied them yet.	Check the entry under Manage domain-wide delegation against the wizard. A new authorization can take a few minutes to apply.
Not verified yet after Check the DNS record	The TXT record is missing, has the wrong name, or has not reached the DNS servers yet.	Compare the record with the wizard’s Name and Value, and check again later.
The test message does not arrive	A mail filter in front of Google Workspace is holding it.	Check the filter’s quarantine and allow the support address.

For a mailbox that stops working later, see Troubleshoot a support mailbox.

Next steps

Email threading
Suspended mail
Forward email to Outpost, if you cannot use delegation

Content is licensed CC BY 4.0. Code samples are MIT. Outpost and the Outpost mark are trademarks of Outpost Business Solutions, PBC and are not covered by either license.