# Gmail

Gmail is Google's email service with over 1.8 billion users. The Sling Gmail connector extracts email data via the Gmail API, supporting messages, threads, labels, and attachments.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

{% tabs %}
{% tab title="Sling CLI" %}
For CLI usage, you need to create your own OAuth 2.0 credentials:

**Secrets:**

* `client_id` **(required)** -> Your Google OAuth 2.0 Client ID
* `client_secret` **(required)** -> Your Google OAuth 2.0 Client Secret

**Inputs (optional):**

* `include_spam_trash` -> Include messages from SPAM and TRASH folders (default: false)
* `extra_query` -> Additional Gmail search query filter (e.g., `from:example@gmail.com` or `subject:invoice`)

#### Creating OAuth 2.0 Credentials

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Navigate to **APIs & Services > Library**
4. Search for "Gmail API" and click **Enable**
5. Go to **APIs & Services > Credentials**
6. Click **Create Credentials > OAuth client ID**
7. If prompted, configure the OAuth consent screen:
   * Choose "External" user type (or "Internal" for Workspace)
   * Fill in required fields (App name, User support email, Developer contact)
   * Add the scope: `https://www.googleapis.com/auth/gmail.readonly`
   * Add your email as a test user
8. Create OAuth client ID:
   * Application type: **Desktop app** (recommended for CLI use)
   * Give it a name (e.g., "Sling Gmail Integration")
9. Download or copy the **Client ID** and **Client Secret**

{% hint style="warning" %}
**OAuth Consent Screen**: For personal Gmail accounts, your app will be in "Testing" mode until verified by Google. You can add up to 100 test users who can authenticate with your app.
{% endhint %}

#### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set GMAIL type=api spec=gmail \
  secrets='{ client_id: your_client_id, client_secret: your_client_secret }'
```

{% endcode %}

#### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export GMAIL='{ type: api, spec: gmail, secrets: { client_id: "your_client_id", client_secret: "your_client_secret" } }'
```

{% endcode %}

#### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  GMAIL:
    type: api
    spec: gmail
    secrets:
      client_id: "your_client_id.apps.googleusercontent.com"
      client_secret: "your_client_secret"
```

**With custom query filter:**

```yaml
connections:
  GMAIL:
    type: api
    spec: gmail
    secrets:
      client_id: "your_client_id.apps.googleusercontent.com"
      client_secret: "your_client_secret"
    inputs:
      extra_query: "from:notifications@github.com"
      include_spam_trash: false
```

{% endtab %}

{% tab title="Sling Platform" %}
On the Sling Platform, simply click **Add Connection** and authenticate with your Google account in the browser. The platform handles OAuth automatically - no credentials needed.

**Inputs (optional):**

* `include_spam_trash` -> Include messages from SPAM and TRASH folders (default: false)
* `extra_query` -> Additional Gmail search query filter (e.g., `from:example@gmail.com` or `subject:invoice`)
  {% endtab %}
  {% endtabs %}

## Replication

Here's an example replication configuration to sync Gmail data to a PostgreSQL database:

```yaml
source: GMAIL
target: MY_POSTGRES

defaults:
  mode: incremental
  object: gmail.{stream_name}

streams:
  # Core data
  labels:
    mode: full-refresh
  profile:
    mode: full-refresh
  messages:
  message_details:
```

**Full data extraction with attachments:**

```yaml
source: GMAIL
target: MY_POSTGRES

defaults:
  mode: incremental
  object: gmail.{stream_name}

streams:
  labels:
    mode: full-refresh
  profile:
    mode: full-refresh
  messages:
  message_details:
  message_attachments:
  threads:
  thread_details:
```

## Endpoints

| Endpoint              | Description                                                              | Incremental |
| --------------------- | ------------------------------------------------------------------------ | ----------- |
| `labels`              | List all labels in the mailbox (Inbox, Sent, custom labels, etc.)        | No          |
| `profile`             | Get user's Gmail profile (email address, history ID, total messages)     | No          |
| `messages`            | List message IDs and thread IDs in the mailbox                           | Yes         |
| `message_details`     | Get full message content, headers, and metadata (iterates over messages) | Yes         |
| `threads`             | List thread IDs and snippets                                             | Yes         |
| `thread_details`      | Get full thread content with all messages (iterates over threads)        | Yes         |
| `message_attachments` | Get attachment content (iterates over message\_details attachments)      | Yes         |
| `drafts`              | List draft messages (disabled by default)                                | No          |

To discover available endpoints:

```bash
sling conns discover GMAIL
```

## Query Filter Examples

Use the `extra_query` input to filter messages:

| Filter                  | Description                        |
| ----------------------- | ---------------------------------- |
| `from:user@example.com` | Messages from a specific sender    |
| `to:me`                 | Messages sent directly to you      |
| `subject:invoice`       | Messages with "invoice" in subject |
| `has:attachment`        | Messages with attachments          |
| `filename:pdf`          | Messages with PDF attachments      |
| `after:2024/01/01`      | Messages after a date              |
| `before:2024/12/31`     | Messages before a date             |
| `is:unread`             | Unread messages only               |
| `label:important`       | Messages with a specific label     |
| `larger:5M`             | Messages larger than 5MB           |

Combine filters with spaces (AND) or `OR`:

```yaml
inputs:
  extra_query: "from:billing@example.com OR from:invoices@example.com has:attachment"
```

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/gmail.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.