# Google Mail

## Overview

Gmail, Google's email service, offers a comprehensive platform for communication and productivity.
With features like advanced search capabilities, powerful filters, and seamless integration with other Google Workspace tools,
Gmail is a cornerstone of modern email management.

By integrating Fours with Gmail, users can leverage automation workflows to enhance email productivity.
Tasks such as sending emails, applying labels for organization, and managing threads can be automated, improving efficiency and enabling customized email workflows tailored to specific needs.

You can connect Gmail at two levels:

- **Org-Level**: Connect once for your organization, so Fours can send automated email from a corporate mailbox that everyone's workflows share. There are **two connection methods** to choose from — a **Service account** with domain-wide delegation, or **Sign in with Google** — described below.
- **User-Level**: Each user connects their own Gmail account via OAuth 2.0, so automated emails are sent from that person's own inbox. The Fours co-sell and commission emails a person's own actions trigger go out from their Gmail too — see [Send Co-Sell Emails from Your Gmail](#send-co-sell-emails-from-your-gmail).

### How the connection works

Whichever method you use, Google issues the credential and Fours refreshes it for you — Fours never holds your Google password. What differs afterwards is *how* a given Gmail operation reaches Google. **Composing operations — creating, updating, sending and deleting drafts, and sending a message — are performed by Fours directly**, so a slow send is not cut short by an action timeout and never leaves you unsure whether the mail went out. Every other Gmail action (labels, filters, send-as aliases, vacation settings) runs through Fours' standard connector path.

```d2
shape: sequence_diagram
you: "You or your Fours admin"
google: "Google"
suger: "Fours"
agent: "Fours AI agent"
you -> google: "Sign in with Google, or authorize a service account"
google -> suger: "Credential — Fours refreshes it for you" { style.stroke-dash: 4 }
compose: "Drafting and sending — run inside Fours" {
  agent -> suger: "Create, update, send or delete a draft; send a message"
  suger -> google: "Gmail call made directly — nothing queued, nothing cut short"
  google -> agent: "Draft id, or the message that was sent" { style.stroke-dash: 4 }
}
rest: "Everything else — labels, filters, send-as, vacation" {
  agent -> suger: "Run the action"
  suger -> google: "Routed through Fours' standard connector"
  google -> agent: "Result" { style.stroke-dash: 4 }
}
```

:::note
The org-level **Service account** method grants the send-only scope and produces a credential that impersonates a mailbox rather than an OAuth grant on it. That is enough for the standard Gmail actions, but **not** for the composing tools above — see [Fours AI Tools](#fours-ai-tools).
:::

## Create Integration (Org-Level)

Org-level Gmail offers **two connection methods**. Both are set up from the same **Gmail** card under **Settings → Integrations**: click the **Connect** dropdown and pick the method you want.

| Method | Choose this when | Scopes granted |
|--------|------------------|----------------|
| **Service account** | You run Google Workspace and want Fours to send as a corporate address (for example `sales@company.com`) with no person signing in and no user's token to expire. Requires a Workspace admin to authorize domain-wide delegation. | **Send only** (`gmail.send`) |
| **Sign in with Google** | You want to authorize a mailbox directly, in a browser, with **no Workspace admin action required** — the fastest path, and the only one available if you are not on Google Workspace. | **Send and read** |

:::tip[Which should I pick?]
Pick **Service account** if you need a durable, admin-governed corporate sender and only ever need to *send*. Pick **Sign in with Google** if you want to be connected in a minute, cannot get a Workspace admin to authorize delegation, or need Fours to *read* mail as well as send it — the send-only scope on the service-account method is deliberate and cannot be widened after the fact.
:::

Your organization connects **one way at a time**. Once connected, the Gmail card shows **"Connected via {method}"** — for example *Connected via Sign in with Google* — so you can always tell which method is in force. To switch methods, delete the integration and connect again with the other one.

![The Gmail card in Settings → Integrations with its Connect control opened — a two-item menu offering "Sign in with Google" and "Service account"](images/gmail-connect-dropdown.png)

### Method 1 — Service account (domain-wide delegation)

This method is designed for company-wide automation where Fours sends email by impersonating a specific corporate address (for example, `sales@company.com`) without a user manually signing in.

1. [Create a service account](https://docs.cloud.google.com/iam/docs/service-accounts-create) in your target GCP project for Google Mail integration.
    :::info
    - Grant the service account with the IAM role `Service Account Token Creator` under the GCP project.
    :::
2. [Enable the Gmail API](https://console.cloud.google.com/apis/api/gmail.googleapis.com/metrics) in the same Google project.
3. [Create the service account key](https://docs.cloud.google.com/iam/docs/keys-create-delete#creating), and download the associated JSON file. It is required for the following integration.
4. [Enable G-Suite Domain-wide Delegation](https://developers.google.com/workspace/guides/create-credentials#optional_set_up_domain-wide_delegation_for_a_service_account) for the service account.
    :::info
    - In the "OAuth Scopes" field, only select the scope `https://www.googleapis.com/auth/gmail.send`.
    :::
5. Specify the impersonated email address, select the appropriate scopes configured in the previous step, and store the JSON key file contents within the Fours console integration page.
    :::info
    - Enter the Impersonation Email (a user email from your company) that Fours will impersonate to send emails on behalf of the user. **It MUST be a user email, instead of a group email**, since the group email can't be impersonated.
    - Select only the scope `https://www.googleapis.com/auth/gmail.send`.
    :::

> ![Google Mail Org Integration](images/google-mail-integration.jpg)

:::warning[**Send as (Workspace user email)** is required]
The connect form asks for **Send as (Workspace user email)** and this field is **not optional** for Gmail. A service account has no mailbox of its own, so a connection without it would be accepted and then fail on every send. It must be a valid Google Workspace **user** email address — a group address cannot be impersonated — and it must be one the domain-wide delegation you authorized in step 4 actually covers.
:::

The default scope for this method is **send only** (`https://www.googleapis.com/auth/gmail.send`). Domain-wide delegation is all-or-nothing: a request asking for any scope your Workspace admin did not authorize fails entirely, so if you need Fours to read mail as well, use **Sign in with Google** instead.

### Method 2 — Sign in with Google (OAuth)

This method authorizes a mailbox directly in the browser, using the same Google OAuth application as the user-level connection. **No Workspace admin action is required**, and it grants both **send and read** scopes.

1. In the Fours Console, go to **Settings → Integrations** and find the **Gmail** card.
2. Open the **Connect** dropdown and choose **Sign in with Google**.
3. You are redirected to the Google sign-in page. Sign in with the mailbox your organization should send from — this is the account every workflow in your organization will send as, so use a shared or role mailbox rather than a personal one.
4. Review the requested access and click **Allow**.
5. Once you are redirected back to the Fours Console, click **Verify**. A **Verified** status confirms the connection is ready.

![The Integrations catalog — the Gmail card showing "Connected via Service account", the label that tells you which of the two org-level methods is in use](images/gmail-connected-via.png)

:::caution
Because this is a normal OAuth grant on a real Google account, it is tied to that account's continued existence and consent. If the mailbox owner leaves and the account is deleted, or someone revokes Fours' access from their Google account, org-wide sending stops until you reconnect. A shared/role mailbox — or the service-account method — avoids that.
:::

## Create User Integration

User-Level integration is personal and precise. It lets Fours send emails that look like they came from you, while automation handles the repetitive work.

- **OAuth 2.0 Security**: Fours never sees, asks for, or stores your Google password. The connection is a secure, token-based handshake.
- **Responsive automation**: Send automated private offer links and follow-up sequences the moment a buyer hits a milestone.
- **Thread management**: Keep your deal discussions organized without jumping between tabs.

1. In the Fours Console, go to **Settings → Integrations** and scroll to the **User Integrations** section. Locate the **Gmail** card and click **Connect**, then click **Start connection** in the **Connect Gmail** dialog.

    > ![Google Mail Connect Now](images/user-integration-connect-gmail-to-suger-1.jpg)

2. You will be redirected to the Google sign-in page. Select the account you want to use for your marketplace deals.
3. Review the request and click **Allow**. This grants Fours the permissions needed to read and send emails related to your marketplace workflows.

    > ![Google Mail User Consent](images/user-integration-connect-gmail-to-suger-2.jpg)

4. When the dialog shows **Gmail is connected.**, click **Close**. The **Gmail** card now shows a green check mark, which confirms Fours is ready to send on your behalf.

## Send Co-Sell Emails from Your Gmail

A user-level Gmail connection also changes who sends your co-sell email. When **your own action** in Fours triggers a Fours co-sell or commission email, Fours sends it from your connected Gmail instead of from that email's usual sender. That covers sharing a deal with a partner, accepting or declining one, marking it Closed Won or Closed Lost, updating a deal, removing a partner, proposing or approving commission terms, and marking a commission payment sent or confirming it.

- **It is the same email.** It keeps the subject and threading that Fours' default sender uses (see the [Partners notification scopes](/settings/email-notification/#partners)) and the same recipients, including the deal's activity address on Cc — so replies sent with **Reply all** still reach the deal's activity feed. Because the email comes from your mailbox, a plain **Reply** reaches you directly, and a copy stays in your Gmail **Sent** folder.
- **There is no setting.** Connecting Gmail as a [user integration](#create-user-integration) turns it on; disconnecting turns it off.
- **If your Gmail can't send, the email still goes out.** If you have no Gmail connection, or its access has expired or been revoked, Fours sends the email from the custom sender configured for that notification if there is one, otherwise from Fours' default sender.
- **Connect in each organization you act from.** A user integration belongs to one Fours organization, so an email goes out from your Gmail only when you connected Gmail in the organization you acted in.
- **Partner organizations can do the same.** A partner's users can connect their own Gmail at user level, so the emails their actions trigger come from their own mailboxes.
- **One-click links work the same way.** When someone completes an action from a one-click link in a co-sell email, the follow-up email goes out from their own connected Gmail, as if they had acted in the console.

These are **never** sent from your mailbox:

- Emails Fours sends on its own — automatic acceptance, scheduled jobs, and webhooks.
- Emails triggered by actions in the Salesforce or HubSpot app, or through the API.
- Copies that carry a personal one-click action link. Those always come from Fours' default sender.
- Copies addressed to recipients that another organization added in its own notification settings.
- Other notifications, such as offer and entitlement emails.

```d2
direction: down
act: "Your action triggers a Fours\nco-sell or commission email"
personal: "Copy carries a personal\none-click action link?" { shape: diamond }
yours: "Eligible for your mailbox, and\nyour user-level Gmail can send?" { shape: diamond }
custom: "Custom sender configured\nfor this notification?" { shape: diamond }
gmail: "Sent from your Gmail"
configured: "Sent from the custom sender"
suger: "Sent from Fours' default sender"
act -> personal
personal -> suger: "yes"
personal -> yours: "no"
yours -> gmail: "yes"
yours -> custom: "no"
custom -> configured: "yes"
custom -> suger: "no"
```

:::note
Only Gmail sends these emails on your behalf. Your own connected [Microsoft Outlook](/integrations/microsoft-outlook/) account is never used for them, because Outlook cannot keep them in the deal's single email thread.
:::

## Fours AI Tools

When Gmail is connected, the Fours AI agent works your mailbox through Fours' built-in tools. The composing tools are the ones you will name most often; they carry a `google_email__` prefix.

| Capability | What the agent can do |
|------------|-----------------------|
| **Compose a draft** | Write a new Gmail draft from a subject, body and recipients — including Cc, Bcc and an HTML body — and get back the draft's id. The draft is saved, never sent (`create-draft`) |
| **Revise a draft** | Replace an existing draft's contents. The whole message is rewritten from the call, so the agent restates the complete draft rather than patching one field (`update-draft`) |
| **Send a draft** | Send a draft that is already saved. Irreversible — the recipient has it immediately (`send-draft`) |
| **Discard a draft** | Delete a draft without sending it (`delete-draft`) |
| **Send a message** | Compose and send in one step, without saving a draft first. Irreversible. Can reply inside an existing conversation rather than starting a new one (`send-message`) |
| **Everything else in Gmail** | Labels, filters, send-as aliases, vacation settings and the rest of the Gmail surface remain available as standard actions on the connection |

You never have to hand the agent a pre-assembled raw email: it supplies the recipients, subject and body as ordinary fields, and Fours builds the message — including correct handling of non-ASCII subject lines.

:::warning[A service-account org connection does not get the composing tools]
The composing tools above need an OAuth grant on a real mailbox. An **org-level Gmail connection created with the Service account method does not have one**, so on that connection the agent gets **none** of `create-draft`, `update-draft`, `send-draft`, `delete-draft` or `send-message` — only the standard Gmail actions remain.

If you want the agent to draft and send, connect Gmail with **Sign in with Google** at the org level, or have each person connect their own Gmail as a [user integration](#create-user-integration). The service-account method is still the right choice when all you need is automated *sending from workflows* out of a durable corporate address.
:::

:::info
Sending is not reversible and the agent knows it: `send-draft` and `send-message` deliver immediately, with no recall window. Prefer having the agent create a draft and reviewing it yourself before a send.
:::

:::tip
Open the integration from **Settings → Integrations** to see the exact tool list for your connection on its **Actions** tab, and to try a call on the **Playground** tab. The Playground pre-fills only the inputs an action *requires* — add optional ones yourself when you need them.
:::

## Edit Integration

> Editing is not supported for security reasons. To change configuration, delete the integration and create a new one.

:::info
- If your OAuth token expires, or you change your Google password or rotate your GCP service account keys, delete the integration in Fours and recreate it to refresh access.
- When switching from a personal to a corporate account, delete the current integration first to ensure no stale tokens remain.
- The org-level Gmail card tells you when its stored credential has stopped working, so you do not have to discover it from a failed send — see [Connection health](/integrations/#connection-health).
:::

## Delete Integration

The Google Mail integration can be deleted like all other integrations. Once the deletion is triggered, all integration info including the service account key and access tokens will be deleted immediately & permanently from Fours. No time window or methods to recover.

:::warning
- For a Service Account integration, also delete the service account and its key in the GCP Console to fully revoke access.
- Deleting the integration in Fours does not automatically revoke permissions granted in Google.
  To fully disable access, the user must also revoke the application's permissions in their Google account.

  Steps to revoke Google permissions:
  1. Go to Google Account → Security
  2. Open Your connections to third-party apps & services
  3. Locate the Fours application with Google Mail access
  4. Click Remove access
:::