Gmail signatures through the Gmail API: setup step by step

What do I need to set Gmail signatures for all users?

• A Google Workspace super admin account.
• Access to the Google Cloud console with the same account (free; no card required).
• About 30 minutes.

This is how every signature management tool for Google Workspace works, SignetMail included. You need the same steps if you write your own script.

1. Project and APIs

1. Sign in to console.cloud.google.com as a super admin and create a new project. Make sure it sits under your organization (not "No organization").
2. APIs & Services → Library: enable the Gmail API and the Admin SDK API.

2. Service account and key

1. IAM & Admin → Service accounts → Create service account. It needs no project role.
2. On the Keys tab: Add key → Create new key → JSON. Keep the file safe — whoever has it can act as the service account.
3. On the Details tab note the Unique ID (a number); you need it in step 3.

Error: "Service account key creation is disabled"

For organizations created in recent years Google enforces the policy iam.managed.disableServiceAccountKeyCreation by default (secure by default). Unlock keys for this project only:

1. IAM & Admin → Manage resources: select the organization and, in the Permissions panel, give yourself the role Organization Policy Administrator. A Workspace super admin does not have it automatically.
2. Select the project and open IAM & Admin → Organization policies.
3. Open Disable service account key creation → Manage policy → Override parent's policy → Add rule → Enforcement: Off → Set policy.
4. Wait a minute and create the key again.

The policy stays in force for every other project in the organization.

3. Domain-wide delegation

In admin.google.com → Security → Access and data control → API controls → Manage domain-wide delegation → Add new, enter the Unique ID from step 2 and the scopes:

https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/admin.directory.user.readonly
https://www.googleapis.com/auth/admin.directory.group.readonly
https://www.googleapis.com/auth/admin.directory.group.member.readonly

The first scope allows changing Gmail settings (including the signature), not reading mail. The other three only read the directory — that is where name, title, department and phone come from. The change usually applies within minutes, but can take up to 24 hours.

4. Setting the signature

With the key, the application gets a token on behalf of the user (subject = their e-mail) and calls:

PATCH https://gmail.googleapis.com/gmail/v1/users/{email}/settings/sendAs/{email}
{ "signature": "<table>…</table>" }

Repeat for every user. Gmail accepts up to 10,000 characters of HTML, strips <style> blocks and shows the signature within a few minutes.

5. Admin sign-in (optional)

If the tool has a web portal with Google sign-in, it also needs an OAuth client: APIs & Services → OAuth consent screen (type Internal), then Credentials → Create OAuth client ID → Web application with the portal address under Authorized JavaScript origins.

Common errors

Frequently asked questions

Can I also put the signature above the quote and remove the "--"?

Not centrally. It is a personal Gmail setting (Settings → General → Signature defaults) that the Gmail API does not expose. Send users a short how-to.

Do I need a script?

For a one-off setup a script is enough. If details change (new hires, titles, campaigns), a tool that keeps signatures up to date is less work. SignetMail uses exactly these steps; see the documentation.

How is this different from the Admin console footer?

See Google Workspace email footer vs. signature.