> For the complete documentation index, see [llms.txt](https://docs.cogram.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cogram.com/email/gmail.md).

# Gmail

Set up Gmail with Cogram: install the Cogram for Gmail extension, connect mailboxes, set organization defaults, file emails from Gmail, and add delegates.

Cogram files project email from Gmail into the right Cogram project:

* **Auto-filing**: files matching incoming emails, and outgoing emails if you turn it on.
* **Cogram for Gmail**: a Chrome extension panel in Gmail. File, unfile, or correct one or more conversations.

> Contact Cogram support to turn on Gmail for your organization.

For a diagram of every way an email gets filed and how Cogram picks the project, see [How email filing works](https://docs.cogram.com/email/how-email-filing-works.md).

## Quick start

Admins: first [set up Gmail for your organization](#set-up-gmail-for-your-organization-admins).

1. Install [Cogram for Gmail](https://chromewebstore.google.com/detail/cogram-for-gmail/mnpdnaoonpinlppmekcadibpfegfikcd) and click **Add to Chrome**. Skip if your admin installed it.
2. [Connect your Gmail](#connect-your-gmail) in Cogram.
3. Open Gmail. In the Cogram panel, click **Sign in with Google**.

## Requirements

* A Google Workspace account. Personal Gmail is not supported.
* Chrome on desktop. Other Chromium browsers (Edge, Brave, Arc) work but ask you to sign in more often. No mobile.

## Set up Gmail for your organization (admins)

Do once, in this order:

1. [Allow Cogram in Google Workspace](#allow-cogram-in-google-workspace), if you restrict third-party apps.
2. [Install the extension for everyone](#install-the-extension-for-everyone).
3. [Set the organization defaults](#set-organization-defaults).
4. Ask each person to [connect their Gmail](#connect-your-gmail).

### Allow Cogram in Google Workspace

> **Who:** a Google Workspace super admin.

Without this, people cannot connect Gmail if you block unconfigured third-party apps.

Cogram has three Google apps, one per sign-in. Trust all three:

| Client ID                                                                | Used for                                   |
| ------------------------------------------------------------------------ | ------------------------------------------ |
| `6792548922-0aach7rgprbgl81k81poujco2526engq.apps.googleusercontent.com` | Connecting Gmail in Cogram                 |
| `6792548922-jclb50dc1blrh4fj19kdomflog4hufp0.apps.googleusercontent.com` | Cogram for Gmail sign-in in Chrome         |
| `6792548922-6lpr8ar9m9r8vh4ng2i3olo8il04pven.apps.googleusercontent.com` | Cogram for Gmail sign-in in other browsers |

1. In the [Google Admin console](https://admin.google.com), go to **Security > Access and data control > API controls**.
2. Under **App access control**, click **Manage third-party app access**.
3. Click **Configure new app**.
4. Search for `cogram` and select **Web**. Each result shows its client ID. Select the Cogram app with the first client ID from the table.

   <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-9b810ace87cd7a4143729d999407d91ce925b0aa%2Fgmail-workspace-trusted-1-select-app.png?alt=media" alt="The Configure new app search in the Google Admin console, with the query cogram, the Web filter on, and three verified Cogram web apps whose client IDs start with 6792548922"><figcaption><p>Select the Cogram app by its client ID</p></figcaption></figure>
5. Under **Scope**, keep **All in** your organization, or choose **Select org units**. Click **Continue**.

   <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-4ff1948cd16973fa31adab4c3c8dd401b9a2f163%2Fgmail-workspace-trusted-2-scope.png?alt=media" alt="The Scope step for the Cogram app, with All in the organization (all users) selected and the Select org units option below it"><figcaption><p>Choose who the setting applies to</p></figcaption></figure>
6. Under **Access to Google Data**, select **Trusted**. Click **Continue**.

   <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-8937154cd53546609d00fea77193548b8afddeb2%2Fgmail-workspace-trusted-3-access.png?alt=media" alt="The Access to Google Data step for the Cogram app, with Trusted selected above the Limited, Specific Google data, and Blocked options"><figcaption><p>Set Cogram to Trusted</p></figcaption></figure>
7. Review the app, scope, and access, then click **Finish**.

   <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-39ffd5e582bfbaef640a75341f74eb8ee15b8861%2Fgmail-workspace-trusted-4-review.png?alt=media" alt="The Review step, listing the Cogram web app with its client ID, one org unit in scope, and Trusted access to Google data"><figcaption><p>Review and finish</p></figcaption></figure>
8. Repeat steps 3–7 for the other two client IDs.

When you are done, **Configured apps** lists three Cogram apps, each with the access you set.

<figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-7589af4e4f03da336d3381f607d806d2d543848d%2Fgmail-workspace-trusted-5-configured-apps.png?alt=media" alt="The Configured apps list in the Google Admin console with three verified Cogram web apps, each configured for one org unit"><figcaption><p>All three Cogram apps configured</p></figcaption></figure>

### Install the extension for everyone

> **Who:** a Google Workspace admin who manages Chrome.

Users see no permission prompt.

1. In the [Google Admin console](https://admin.google.com), go to **Devices > Chrome > Apps & extensions > Users & browsers**.
2. Select the organizational unit.
3. Add a Chrome app or extension by ID: `mnpdnaoonpinlppmekcadibpfegfikcd`.
4. Set the installation policy to **Force install**, and save.

Windows Group Policy or macOS MDM: add the same ID to `ExtensionInstallForcelist`.

### Set organization defaults

> **Who:** a Cogram Org Admin or Owner.

1. Go to [**Organization Settings > Emails**](https://app.cogram.com/dashboard/settings/admin/email).
2. Under **Auto-filing**, find **Gmail**.
3. Set each default. Lock it to stop users from changing it.

| Setting                                   | Default | What it does                                                              |
| ----------------------------------------- | ------- | ------------------------------------------------------------------------- |
| **Auto-file incoming emails to projects** | On      | Files incoming emails to the projects they match.                         |
| **Auto-file outgoing emails to projects** | Off     | Files emails your team sends to the projects they match.                  |
| **Apply Gmail labels**                    | On      | Marks processed emails with a Gmail label that shows their filing status. |

Also on this page:

* **Show labels for all projects**: default on. Each user gets a label for every project they are a member of, before any email is filed there. An admin in many projects gets many labels. Shows only if your organization uses a label per project.
* **Filing labels**: name and color of the root label for project labels. Default: `Cogram filed`. Shows only if your organization uses a label per project.
* **Labels excluded from filing**: keep conversations out of auto-filing. See [Keeping a conversation out of auto-filing with a label](https://docs.cogram.com/email/emails.md#keeping-a-conversation-out-of-auto-filing-with-a-label-admins).
* [Delegated accounts](#manage-delegates-for-your-organization).

## Connect your Gmail

Everyone connects their own mailbox once. Until then, nothing files from your Gmail.

1. Go to [**Account Settings > Integrations**](https://app.cogram.com/dashboard/settings/account-settings/integrations).
2. In **Email**, find **Gmail** and click **Connect**.
3. Sign in with your work Google account and allow access.

**Expected result:** "Gmail connected", and the Gmail row shows your email with a connected badge.

### Your Gmail settings

* **Auto-file incoming emails**
* **Auto-file outgoing emails**
* **Apply Gmail labels**: label filed emails in your mailbox.
* **Show labels for all my projects**: add a label for each project you are a member of, before any email is filed there. New projects get their label within an hour. Turning it off keeps the labels you have.

Grayed out with a lock icon: your organization locked it. Ask your Org Admin.

To stop, click **Disconnect Gmail** and confirm. Your mailbox stays untouched.

## File emails from Gmail

1. Open Gmail in Chrome. The Cogram panel is on the right.
2. First time only: click **Sign in with Google** with the account you connected.
3. Open a conversation, or check several in the list.

**One conversation:** see its status and projects. Then:

* Confirm or reject a suggested project.
* Search for a project and file to it.
* Unfile from a project.

**Several conversations:** see how many are filed, and where. File all to one project, or unfile all from one.

With Contract admin, choose what filing creates: an email, an RFI, a submittal, or a change order. You get one record per conversation, from its first message.

Actions apply to the whole conversation.

### Labels in your mailbox

With **Apply Gmail labels** on:

* Filed: **Filed**, or one label per project, under your organization's root label.
* Processed, not filed: **Not filed**.
* Maybe confidential: **Confidential**. See [Confidential email](https://docs.cogram.com/email/confidential-email.md).

The extension labels right away when you file or unfile.

A project label you add yourself in Gmail does not file the email to Cogram. To file, use the Cogram panel.

### Limitations

* Bulk filing runs in your browser, five at a time. Close the tab and unstarted conversations are not filed. Finished ones stay filed.
* The panel floats over Gmail. It does not resize the page.

## Gmail delegated accounts

A delegate has Gmail delegation to your mailbox, for example an assistant. Add their email in Cogram, and they can file in your mailbox with your project access. They need no Cogram account.

> Contact Cogram support to turn on delegated accounts for your account or organization.

**Limitations**

* A Cogram account email can't be a delegate.
* One delegate email serves one Cogram user only.
* Cogram does not check the Gmail delegation. Set it up in Gmail first.

### Add a delegate

**Prerequisites:** your Gmail is connected, and the delegate has Gmail delegation to your mailbox.

1. Go to [**Account Settings > Integrations**](https://app.cogram.com/dashboard/settings/account-settings/integrations).
2. In **Email**, under **Gmail**, find **Delegated accounts**.
3. Enter the delegate's email and click **Add**.

**Expected result:** the email shows as **Active**. If it fails, the reason shows under the field.

To remove: click the trash icon, then **Remove**.

| Status                                                             | Meaning                                                                                             |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| **Active**                                                         | The delegate can use the extension.                                                                 |
| **Connect Gmail to activate** (admins see **Gmail not connected**) | The delegator's Gmail is not connected to Cogram. Connect it to activate the delegates.             |
| **Account inactive**                                               | The delegator's Cogram account is deactivated.                                                      |
| **Already a Cogram user**                                          | Someone signed up for Cogram with this email after it was added. It can't be a delegate. Remove it. |

### What the delegate sees

1. The delegate installs Cogram for Gmail and signs in with their own Google account.
2. They open your mailbox in Gmail. The extension does not work in their own mailbox.
3. The panel shows **Acting on behalf of** your name and email.

For a delegate, Gmail labels appear only when Cogram finishes filing.

### Manage delegates for your organization

Org Admins can manage every user's delegates.

1. Go to [**Organization Settings > Emails**](https://app.cogram.com/dashboard/settings/admin/email).
2. Open **Delegated accounts**: delegator, delegate, added by, and status.

   <figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-f065c96138a83d10e4f14a29df0e38cd86fc8d1a%2Forg-settings-delegated-accounts.png?alt=media" alt="The Delegated accounts table in Organization settings, with Import and Add delegate buttons and columns for delegator, delegate, added by, and status"><figcaption><p>Delegated accounts in Organization settings</p></figcaption></figure>
3. To add: click **Add delegate**, select the user, enter the delegate's email, and click **Add**.
4. To remove: click the trash icon on the row, then **Remove**.

### Import delegates from a file

1. Click **Import**.
2. Click **Download template**. CSV or XLSX, up to 5 MB and 5,000 rows, two columns:
   * `delegator_email`: a user in your organization.
   * `delegate_email`: the delegate.
3. Upload the file and select a mode.
4. Click **Review changes**. Each row shows as new, moved, unchanged, removed, or error. Nothing changes yet. Check errors and, in **Rewrite** mode, how many delegates get removed.
5. Click **Import**.

| Mode        | New delegates | Delegate that already works for another user | Delegates not in the file |
| ----------- | ------------- | -------------------------------------------- | ------------------------- |
| **Add**     | Added         | Flagged as an error                          | Kept                      |
| **Update**  | Added         | Reassigned to the user named in the file     | Kept                      |
| **Rewrite** | Added         | Reassigned to the user named in the file     | **Removed**               |

**Expected result:** rows without errors apply. Fix error rows in the file and import again.

## Troubleshooting

### Connecting Gmail

#### Connect does nothing

**Connect** does nothing, or "Allow popups for this site, then try connecting again."

* **Likely cause:** Popup blocked.
* **Fix:** Allow popups for app.cogram.com, then click **Connect** again.

#### Google blocks access

Google says access is blocked, or your admin must approve the app.

* **Likely cause:** Your Workspace restricts third-party apps.
* **Fix:** Ask your Workspace admin to [allow Cogram](#allow-cogram-in-google-workspace).

#### Gmail is not set up correctly

"Gmail is not set up correctly on Cogram's side. Contact Cogram support."

* **Likely cause:** A problem on Cogram's side. Retrying does not help.
* **Fix:** Contact Cogram support.

#### No Gmail under Integrations

No **Gmail** in **Account Settings > Integrations**.

* **Likely cause:** Gmail is off for your organization.
* **Fix:** Contact Cogram support.

### Filing from the panel

#### Asked to connect Gmail

"Connect Gmail in Cogram to file email from here."

* **Likely cause:** Your mailbox is not connected.
* **Fix:** [Connect your Gmail](#connect-your-gmail).

#### Frequent sign-in prompts

The panel often asks you to sign in again.

* **Likely cause:** Not Chrome, or your Chrome profile is not signed in to the connected Google account.
* **Fix:** Use Chrome, signed in with your work Google account.

#### Filing takes a few minutes

"This can take a few minutes. The panel updates by itself."

* **Likely cause:** Large attachments.
* **Fix:** Wait. Do not file again. The spinner (or progress bar) stays until filing finishes. If you leave, filing continues. Reopen the conversation to check.

#### Filing takes longer than expected

"Filing is taking longer than expected. Check back later to see if it was filed."

* **Likely cause:** Filing still running after about 10 minutes.
* **Fix:** Reopen the conversation later.

#### Warning after filing

A warning after filing, for example attachment processing failed.

* **Likely cause:** The email filed, but its attachments did not save. For several conversations, see the summary notice.
* **Fix:** Contact Cogram support if you need the attachments.

### Delegates

#### Delegate is a Cogram user

"... is a Cogram user in your organization and can't be a delegate."

* **Likely cause:** The email is a Cogram account.
* **Fix:** Share projects with them instead.

#### Already a delegate

"... is already a delegate of ..."

* **Likely cause:** A delegate email serves only one user.
* **Fix:** Ask an admin to remove it from the other user, or import in **Update** mode.

#### Address already in use

"... is already in use."

* **Likely cause:** A Cogram account or a delegate in another organization.
* **Fix:** Use a different email, or contact Cogram support.

#### Signed in as a delegate

"You're signed in as a delegate of ... Switch to that mailbox in Gmail to file emails."

* **Likely cause:** The delegate opened the wrong mailbox.
* **Fix:** Open your mailbox. The delegate must be signed in to Chrome with the Google account you added.

#### No active Cogram account

"... no longer has an active Cogram account."

* **Likely cause:** Your Cogram account is deactivated.
* **Fix:** Ask an admin to reactivate it.

#### Gmail not connected in Cogram

"... hasn't connected Gmail in Cogram."

* **Likely cause:** Your Gmail is not connected.
* **Fix:** [Connect your Gmail](#connect-your-gmail).

## Next steps

* [Emails](https://docs.cogram.com/email/emails.md): work with filed emails.
* [Confidential email](https://docs.cogram.com/email/confidential-email.md)
* [Importing emails](https://docs.cogram.com/email/importing-emails.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cogram.com/email/gmail.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
