Chrome extension and Google Workspace add-on

Gmail integration

5 min readUpdated August 2026

Most of a practice's work arrives by email. The Gmail integration turns a message into an Xedul task linked to the right client and case, with attachments imported, without leaving the inbox.

Two routes

Xedul offers two distinct Gmail integrations. They aren't alternatives to deliberate over for long: the choice follows how the practice uses Gmail.

	Chrome extension	Workspace add-on
Where it lives	In the browser, inside the Gmail page	In the Gmail side panel
Installation	Per browser	Distributed across the Workspace domain
Suits	People working in Gmail on the web from a fixed machine	Practices on Google Workspace wanting central distribution
Attachment access	Whatever Gmail exposes in the page	Through the Gmail API, more complete

If the practice runs Google Workspace, the add-on is generally the better choice: it's distributed once for everyone and imports attachments more reliably.

Chrome extension

Installation

Open Chrome and go to chrome://extensions.
Enable Developer mode, top right.
Choose Load unpacked and select the Xedul extension folder.
Click the extension icon and check the Xedul URL: https://xedul.com for production, or a local address during development.
Enter your Xedul email and password and confirm sign-in.

The session is saved in the browser and refreshed automatically where possible: you don't sign in on every use.

Using it

Open Gmail on the web and open the message you want to work.
Click the Xedul button that appears in the page.
Xedul opens the tasks page with a pre-filled draft built from the message.
Check the fields, link client and case, set priority and due date.
Save.

What gets imported

The message subject
The sender
The date
The visible body of the message
Attachments, when Gmail exposes them as downloadable in the page

In the Chrome extension, attachment import is best effort: if Gmail doesn't expose a downloadable URL inside the page, the attachment is skipped. The rest of the message imports normally. For more reliable import, use the Workspace add-on.

How the session is handled

The Xedul token is stored in the extension's local storage together with the refresh token, separately from the application's cookies. The script running inside the Gmail page neither reads nor stores tokens: authentication and API calls are handled by the extension's service worker.

Google Workspace add-on

The add-on shows Xedul in the Gmail side panel as a Google Workspace add-on, independently of the Chrome extension.

What it does

Authenticates the user against Xedul with email and password.
Stores access and refresh tokens in the script's user properties.
Refreshes the Xedul session silently.
Reads the selected Gmail message.
Saves a temporary draft server-side, avoiding excessively long URLs.
Opens Xedul on the tasks page, reusing the same window the Chrome extension uses.
Shows the task form beside the message preview.
Imports attachments after Xedul has opened.

Deferred attachment import

The add-on initially saves only the message metadata, the preview and an authorisation block used server-side only, which is never returned to the browser.

When the Xedul window opens, the backend uses that authorisation to read the attachments from Gmail, uploads them into document storage, and updates the draft with references to the imported files. The authorisation is then removed.

This design has two practical consequences: the panel opens immediately, without waiting for attachments to load, and the Gmail token never passes through the browser.

Installation and testing

Create an Apps Script project.
Copy the add-on manifest and code into the project.
Configure the OAuth consent screen in Google Cloud for the scopes the manifest requires.
Deploy as a test Google Workspace add-on.
Open Gmail, install the add-on and sign in to Xedul from the side panel.

Changing OAuth scopes requires a fresh authorisation from the test user. It isn't a step you can skip.

The Xedul address during testing

Apps Script cannot call localhost. To test the add-on against a local instance you need to expose the application over a public HTTPS tunnel and use that origin.

The Xedul address is resolved in this order:

The script property XEDUL_BASE_URL.
The address saved in the test user's sign-in session.
The default value in the add-on code.

To change it:

Open the Apps Script project.
Go to Project Settings › Script Properties.
Add or update XEDUL_BASE_URL with the public HTTPS origin, without a trailing slash.
Save.
In Gmail, reload the add-on or reopen the side panel.

If the user already signed in against a different address, sign out and back in after the change: the sign-in flow stores the resolved address.

The complete flow

The message arrives in the practice's inbox.
Xedul opens from the extension or the side panel, already signed in.
The draft is pre-filled: subject, sender, body and attachments.
You complete the context: client, case, assignee, priority, due date.
You save, and the task is created already linked in the right place.

The task is created only when the user confirms. The draft stays a draft until you decide: nothing enters Xedul without an explicit action.

Troubleshooting

Symptom	Likely cause	What to do
The Xedul button doesn't appear in Gmail	Extension inactive, or the page loaded before installation	Check the extension in `chrome://extensions` and reload Gmail
Sign-in is requested every time	Session can't be refreshed	Sign out and back in from the extension; check the configured Xedul URL
Attachments don't arrive	Chrome extension, attachments not exposed by the page	Use the Workspace add-on
The add-on can't reach Xedul	`localhost` address, or an expired tunnel	Set `XEDUL_BASE_URL` to a valid public HTTPS origin
Authorisation error after an update	OAuth scopes changed	Re-authorise the add-on with the test user
The draft opens empty	No message selected when the panel opened	Open the message and reopen the panel