Google Workspace (Gmail)

Send email through the Gmail API, authenticated with a service account impersonating a mailbox in your domain.

Preferable to SMTP for a Google school: there is no password to rotate, no app password to leak, and no SMTP AUTH setting to discover is disabled.

Category	Email
Authentication	Service account with domain-wide delegation
Reaches	oauth2.googleapis.com, gmail.googleapis.com
Needs an agent	No
Demo mode	No

Capabilities

email.send

Creating the service account

The same flow as Chrome Enterprise and Google Sheets. If you have already made one, reuse it and add the scope.

1. Google Cloud console, in a project for your school.
2. IAM and Admin, Service Accounts, Create service account. Name it plugboard. No project roles are needed.
3. Open it, then Keys, Add key, Create new key, JSON. Download it.
4. On the Details page, copy the Unique ID, a long number. That is the client id for delegation.
5. Make sure the Gmail API is enabled for the project, under APIs and Services, Library.

Granting delegation

1. Google Admin console, Security, Access and data control, API controls, Domain-wide delegation, Add new.

2. Client ID: the Unique ID from step 4.

3. OAuth scope:

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

4. Authorise.

gmail.send is send-only. It cannot read anything in the mailbox, which is the correct scope for this job and worth pointing out if somebody asks what the service account can see.

Choose the sending mailbox

Delegation means the service account acts as a real mailbox. Pick one that:

• exists in your domain,
• is not a person’s, so it survives them leaving,
• has a name a recipient will recognise, such as helpdesk@yourschool.edu.au.

A Google Group will not work. It must be a mailbox.

Configuring it in Plugboard

Admin, Connectors, Google Workspace (Gmail), Configure.

Settings

Field	Value
senderEmail	The mailbox to send as

Credentials

Field	Value
clientEmail	client_email from the downloaded JSON
privateKey	private_key from the JSON, including the BEGIN and END lines

Paste the private key exactly as it appears in the JSON, newlines and all.

Save and test. Success reports “Authenticated with Google”.

What it sends

Messages are sent as senderEmail, so they appear in that mailbox’s Sent folder. That is genuinely useful: everything Plugboard has emailed is visible in a place your team can search, without any extra logging.

Messages are plain text. See email messages for why, and for how to change the wording.

Deliverability

Sending through Gmail as a real mailbox in your domain means SPF and DKIM are already correct, assuming your domain is set up properly for Workspace. That is the main practical advantage over an arbitrary SMTP relay.

Testing properly

The connector test proves authentication. It does not prove delivery.

Lodge a test repair against yourself, confirm the tracking email arrives, and click the link. A broken link means PUBLIC_URL is wrong rather than email being broken.

Troubleshooting

Symptom	Cause
unauthorized_client	Delegation was not authorised for this client id, or the scope string does not match exactly
403 with “Precondition check failed”	The Gmail API is not enabled for the project
400 invalid_grant	The private key is malformed. Paste it complete, with BEGIN and END lines
403 naming the sender	senderEmail does not exist, or is a group rather than a mailbox
Authenticates, nothing arrives	Check the sending mailbox’s Sent folder. If it is there, the problem is at the recipient
Sends stopped after a domain change	The sending mailbox was renamed or removed

Alternatives

SMTP for anything else. Console email for development.