Gmail

Connect & Ingest data from 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.

CLI Pro Required: APIs require a CLI Pro token or Platform Plan.

Setup

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:[email protected] or subject:invoice)

Creating OAuth 2.0 Credentials

1. Go to the Google Cloud Console

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

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.

Using sling conns

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

Environment Variable

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

Sling Env File YAML

See here to learn more about the sling env.yaml file.

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

With custom query filter:

connections:
  GMAIL:
    type: api
    spec: gmail
    secrets:
      client_id: "your_client_id.apps.googleusercontent.com"
      client_secret: "your_client_secret"
    inputs:
      extra_query: "from:[email protected]"
      include_spam_trash: false

Sling Platform

Replication

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

source: GMAIL
target: MY_POSTGRES

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

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

Full data extraction with attachments:

source: GMAIL
target: MY_POSTGRES

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

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:

sling conns discover GMAIL

Query Filter Examples

Use the extra_query input to filter messages:

Filter	Description
from:[email protected]	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:

inputs:
  extra_query: "from:[email protected] OR from:[email protected] has:attachment"

If you are facing issues connecting, please reach out to us at [email protected], on discord or open a Github Issue here.