Home User guide Google Integration Guide (Google Workspace + Gmail) — Signature Manager

Google Integration Guide (Google Workspace + Gmail) — Signature Manager

Last updated on Dec 30, 2025

This guide explains how to connect Signature Manager to Google Workspace, how the integration works “from both sides” (admin + end user), and how to design signatures using placeholders (including conditional logic) for the best possible experience.

Who this guide is for

  • Google Workspace admins who need to deploy consistent Gmail signatures across users.

  • IT / Operations teams managing Organizational Units (OUs) and Groups.

  • Signature designers who build templates using placeholders that pull data from Google Directory and Company Information.

1) What Signature Manager connects to in Google

Signature Manager integrates with Google Workspace using Domain‑Wide Delegation (DWD) via a Google service account. That allows the system to impersonate users to read Directory profile details and to set each user’s Gmail signature through the Gmail Settings API.

What we read from Google (Directory profile fields)

The template editor supports user “Details” placeholders based on Google Workspace user profile fields (Admin SDK Directory API). In our app, these fields are used for preview and assignment accuracy:

  • Name (full name)

  • Primary email

  • Job title

  • Department

  • Phones (work, mobile, home)

  • Addresses (formatted / primary)

  • Employee ID (from external IDs)

  • Profile photo (thumbnail URL, when available)

  • Admin flag (used to determine admin eligibility)

What we write to Google (Gmail signature)

When signatures are applied, Signature Manager updates the user’s Gmail signature using Gmail’s settings endpoint:

  • Updates signature via Gmail Settings (sendAs.patch) for the target user.

2) Google Workspace requirements (Admin-side)

Admin role requirement

To connect a Workspace domain and manage signatures at scale, you must sign in with an account that is a Google Workspace administrator. The system checks admin status through Directory.

Domain‑Wide Delegation (DWD) is required

Because signatures are set for users (often in bulk), your Workspace must allow domain-wide delegation so the service can impersonate users to:

  • Read Directory data

  • Write Gmail signatures

  • (Optionally) handle assets that may be stored/served as part of signature rendering

API scopes (what Google must authorize)

Your Workspace configuration must permit the service account to use scopes like:

  • Admin SDK Directory (read-only)

    • Users, customer, groups, org units, domain

  • Gmail settings (basic)

    • To set signatures

  • Drive scope (used by the backend integration for asset handling in some flows)

In plain terms: Directory read + Gmail signature write are the two core requirements for the integration.

Marketplace / “installed to everyone” note

In some flows, non-admin users may be blocked unless the Workspace has allowed/installed the app appropriately for the org (“installed to Everyone” / permitted in Admin Console). If non-admin users are having trouble joining the org, verify those Marketplace/admin-console settings.

3) What the end user experiences (User-side)

Most users don’t need to do anything once the admin has connected and assigned templates.

Typical outcomes:

  • Their signature is applied automatically when the admin assigns a template to them (directly, via group, via OU, or “all users”).

  • If the admin updates a template and chooses to reapply, the user’s signature updates again.

  • Users may see changes after automation runs (if automation is enabled on the template).

4) How Signature Manager works in our app (High-level)

Step 1 — Choose how to start

Admins can create a new signature template by:

  • Starting from a template

  • Creating from scratch

  • Loading from an existing user’s current signature as a starting point

Step 2 — Design (the editor + placeholders)

This is where you build the signature body (HTML/rich text) and insert placeholders.

Key behavior:

  • You can drag/drop or click placeholders into the editor.

  • The preview renders placeholders using:

    • real user data (if you select a Google Workspace user for preview)

    • otherwise sample data + your organization data (Company Information)

Step 3 — Targeting (who gets it)

You can assign a template to:

  • All users (only one active “all users” template is allowed at a time)

  • Specific users

  • Groups

  • Organizational Units (OUs)

Step 4 — Save & Assign

When saving, you can choose:

  • Reapply signatures to assigned users immediately

  • Enable 24-hour automation for ongoing enforcement/updates

5) Placeholders (the most important part)

Placeholders let you build one template that renders uniquely per employee.

Placeholder syntax: user and company fields

Most placeholders look like:

  • {{employee_name}}

  • {{employee_email}}

  • {{employee_title}}

  • {{company_name}}

  • {{company_website}}

Common “Details” placeholders (Google user profile)

  • {{employee_name}} (Full name)

  • {{employee_email}} (Primary email)

  • {{employee_title}} (Job title)

  • {{employee_department}} (Department)

  • {{employee_W_phone}} (Work phone)

  • {{employee_mobile}} (Mobile)

  • {{employee_H_phone}} (Home phone)

  • {{employee_address}} (Address)

  • {{employee_id}} (Employee ID)

Company placeholders (Company Information in the app)

These come from the org settings page in Signature Manager:

  • {{company_name}}

  • {{company_email}}

  • {{company_phone}}

  • {{company_website}}

  • {{company_address}}

  • {{company_logoURL}} (logo URL)

Social placeholders

Social links are stored at the organization level and inserted as icon elements. For email compatibility, the icons must use absolute URLs to render in Gmail.

Best practice: Fill your social fields in Company Information so every template has consistent links.

6) Conditional placeholders (avoid ugly blanks)

Real directory data is messy: not everyone has a mobile number, job title, department, etc. Conditional blocks prevent broken formatting.

Conditional syntax

Use:

{if employee_title}employee_title{/if}

Conceptually, this means:

  • If employee_title is present, render it.

  • If it’s empty, render nothing.

Examples (recommended patterns)

Hide the entire line when missing

{if employee_mobile}Mobile: employee_mobile{/if}

Hide separators (pipes / bullets) when missing

Instead of:

{{employee_title}} | {{employee_department}}

Use:

{if employee_title}employee_title{/if}{if employee_department} | employee_department{/if}

(Adjust formatting to your desired style.)

Caveat: keep “inside content” simple

In our editor/preview logic, conditionals are evaluated by matching the field name and replacing occurrences inside the conditional block. For best results:

  • Put the field name exactly inside the block (as shown).

  • Avoid nesting conditionals.

  • Avoid complex HTML spanning across {if ...} boundaries.

7) Images: profile pictures, QR codes, and company logos

Email signatures are sensitive to how images are embedded. Here’s how our app behaves.

Company logo

  • Store the logo URL in Company Information.

  • Use {{company_logoURL}} in your template, or insert the logo placeholder from the UI.

  • In preview, the app replaces logo placeholders with the real logo URL when available.

Best practices

  • Use a publicly accessible HTTPS URL

  • Use a reasonably sized image (email-safe sizes)

  • Avoid requiring authentication to view the image

Employee profile picture

The editor can show a placeholder image while designing, but on save the system converts the placeholder back into a token so it can be rendered correctly later.

Best practices

  • Expect some users to have no photo in Directory; pair with conditionals if your design depends on it.

  • Keep the profile photo size email-friendly.

QR codes

The editor uses a visual placeholder; before saving it converts back into {{qr}}.

Best practices

  • Ensure the QR code has a clear destination (vCard/contact data or a profile link).

  • Don’t rely on QR as the only way to contact someone.

8) Targeting strategy (best UX + least admin work)

Recommended approach

  • Use OUs for broad segments (Departments, Regions).

  • Use Groups for cross-cutting segments (Sales team, Leadership team).

  • Use Users for exceptions (executives, contractors).

“All users” rule

Only one active template can be set to “Apply to all users” at once. If you already have an “all users” template active, you’ll need to switch that template to a more specific assignment type before enabling another.

9) Common pitfalls (and how to avoid them)

Placeholder mismatch / empty directory fields

  • Problem: fields render blank or leave awkward punctuation.

  • Fix: use conditional placeholders for any field that isn’t guaranteed (mobile, title, department, address, home phone, employee ID).

Social icons not rendering

  • Problem: icons show broken images in Gmail.

  • Fix: icons must use absolute URLs and be publicly accessible. Configure social links in Company Information.

Images blocked by Gmail

  • Problem: Gmail blocks images until the recipient chooses “Display images.”

  • Fix: this is normal for many recipients. Keep the signature readable even without images (don’t put critical info only in an image).

Overly complex HTML / layout breaks

  • Problem: signature looks great in editor but breaks in Gmail.

  • Fix: keep layouts simple:

    • Tables are usually safer than advanced CSS

    • Avoid complex positioning, scripts, and external CSS

10) Best-practice signature template checklist

  • Required contact info is text, not only in images.

  • Conditional blocks used for optional fields:

    • Mobile

    • Department

    • Title

    • Address

    • Employee ID

    • Home phone

  • Logos/icons use public HTTPS URLs.

  • No double “all users” templates active.

  • Preview with real users (pick a user with sparse data and one with full data).

11) Quick “admin setup” checklist (copy/paste)

  • Confirm you’re signing in as a Workspace admin

  • Ensure Domain‑Wide Delegation is configured for the service account

  • Ensure required scopes are authorized (Directory + Gmail settings, etc.)

  • In Signature Manager:

    • Set Company Information (logo URL, website, social links)

    • Build a template using placeholders + conditionals

    • Assign to Users / Groups / OUs (or All Users)

    • Enable automation if you want daily enforcement

If you want, I can tailor this to your Help Center format

Two quick questions so I can finalize it exactly how you want:

  1. Do you want it written as “Signature Manager for Gmail” (that name appears in your internal docs), or as “Signature Manager” (general brand)?

  2. Should the guide include exact placeholder tables (all keys) in the public article, or keep it “best practices + top placeholders only”?

Status

  • Exploration: completed (placeholders, conditional logic, assignment rules, Google APIs/scopes, signature write method).

  • Deliverable: draft guide provided above; ready to refine into your final Help Center article based on your preferred naming + level of detail.