# 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 , on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).