# 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 Suger 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 using a Service Account with domain-wide delegation, so Suger can send automated emails on behalf of a corporate mailbox without a user signing in.
- **User-Level**: Each user connects their own Gmail account via OAuth 2.0, so automated emails are sent from that person's own inbox.

## Create Integration (Org-Level)

Org-Level Gmail uses a **Service Account with domain-wide delegation**, designed for company-wide automation where Suger 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 Suger console integration page.
    :::info
    - Enter the Impersonation Email (a user email from your company) that Suger 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)

## Create User Integration

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

- **OAuth 2.0 Security**: Suger 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 Suger Console, go to the **User Integrations** section (under your profile settings). Locate the **Google Mail** card and click **Connect Now**.

    > ![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 Suger 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. Once you are redirected back to the Suger Console, find your new integration and click **Verify**. A **Verified** status confirms Suger is ready to send on your behalf.

## Suger AI Tools

Suger AI uses a **middleware** strategy — wrapping the Gmail API directly.

**Profile & Labels**

| Tool | Description |
|------|-------------|
| `googlemail_get_profile` | Get the authenticated user's Gmail profile |
| `googlemail_list_labels` | List all Gmail labels (system and user-created) |

**Messages**

| Tool | Description |
|------|-------------|
| `googlemail_list_messages` | List messages using Gmail search syntax |
| `googlemail_get_message` | Get a message (headers by default) |
| `googlemail_get_message_body` | Get a message with fully decoded body (plain text + HTML) |
| `googlemail_send_mail` | Send an email (plain text, HTML, or threaded reply) |
| `googlemail_reply_to_message` | Reply to a message, preserving thread |
| `googlemail_modify_message_labels` | Add or remove labels on a message |
| `googlemail_batch_modify_messages` | Apply label changes to up to 1,000 messages at once |
| `googlemail_get_attachment` | Download a message attachment |
| `googlemail_trash_message` | Move a message to Trash |
| `googlemail_untrash_message` | Restore a trashed message |

**Threads**

| Tool | Description |
|------|-------------|
| `googlemail_list_threads` | List conversation threads |
| `googlemail_get_thread` | Get all messages in a thread |
| `googlemail_modify_thread_labels` | Add or remove labels on an entire thread |
| `googlemail_trash_thread` | Trash an entire thread |
| `googlemail_untrash_thread` | Restore a trashed thread |

**Drafts**

| Tool | Description |
|------|-------------|
| `googlemail_list_drafts` | List drafts |
| `googlemail_create_draft` | Save an email as a draft |
| `googlemail_get_draft` | Get a draft |
| `googlemail_update_draft` | Replace a draft's content |
| `googlemail_send_draft` | Send a previously saved draft |
| `googlemail_delete_draft` | Permanently delete a draft |

## 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 Suger 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.
:::

## 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 Suger. 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 Suger 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 Suger application with Google Mail access
  4. Click Remove access
:::