Skip to main content

Gmail

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable Self-Managed EnterpriseAvailable PyAirbyte
Support Level
Marketplace
Connector Version
0.1.1 (last updated 17 days ago)
Definition ID
f7833dac-fc18-4feb-a2a9-94b22001edc6

This page contains the setup guide and reference information for the Gmail source connector.

Gmail is the email service provided by Google. The Gmail source connector replicates messages, drafts, threads, labels, and the authenticated user's profile from Gmail's REST API.

Prerequisites​

  • A Google account with access to the mailbox you want to replicate.
  • The OAuth scope https://www.googleapis.com/auth/gmail.readonly. The connector reads from Gmail and never modifies messages, labels, or settings.
  • For Airbyte Open Source: a Google Cloud project with the Gmail API enabled, plus either an OAuth 2.0 client and refresh token, or a service account key.

Setup guide​

Step 1: Set up authentication​

The Gmail source connector supports two authentication methods: OAuth and Service Account Key. Both methods require the https://www.googleapis.com/auth/gmail.readonly scope.

In Airbyte Cloud, sign in with the Google account whose mailbox you want to replicate. Airbyte Cloud handles the OAuth flow for you — you only need to authorize Airbyte through the standard Google consent screen when configuring the source.

OAuth for Airbyte Open Source​

To authenticate with OAuth in Airbyte Open Source, create your own OAuth client in your Google Cloud project and complete the authorization code flow yourself to obtain a refresh token. You will need the resulting Client ID, Client Secret, and Refresh Token to configure the connector.

  1. In the Google Cloud console, enable the Gmail API for your project.
  2. Configure your OAuth consent screen and add the https://www.googleapis.com/auth/gmail.readonly scope. See Choose Gmail API scopes.
  3. Follow Google's web server OAuth 2.0 guide to create a Web application OAuth client and exchange the authorization code for a refresh token.

Service Account Key for Airbyte Open Source​

You can also authenticate with a Google service account key. Because Gmail mailboxes are owned by individual users, the service account must use domain-wide delegation to access mailboxes in a Google Workspace domain.

  1. Open the Service Accounts page in your Google Cloud console and create a new service account, or select an existing one.
  2. In the Keys tab, click Add Key > Create new key, select JSON, and download the key file. Store it securely — Google does not let you re-download it.
  3. In your Google Workspace admin console, enable domain-wide delegation for the service account's client ID and authorize the https://www.googleapis.com/auth/gmail.readonly scope.
note

Only a Google Workspace super administrator can configure domain-wide delegation. Domain-wide delegation lets the service account impersonate users in your Workspace organization to read their mailboxes.

Step 2: Set up the Gmail connector in Airbyte​

  1. Log into your Airbyte instance, click Sources, and click + New source.
  2. Select Gmail from the source type dropdown.
  3. Choose your authentication method:
    • Authenticate via Google (OAuth) — Click Authenticate your account and complete the Google sign-in flow. Airbyte Cloud users authenticate against Airbyte's pre-registered OAuth app. Airbyte Open Source users provide their own Client ID, Client Secret, and Refresh Token.
    • Service Account Key Authentication — Paste the contents of your service account JSON key file into the Service Account Information field.
  4. (Optional) Set Start date in YYYY-MM-DDTHH:MM:SSZ format. Only messages, drafts, and threads received on or after this date are replicated. If you leave it blank, the connector replicates the full mailbox history.
  5. (Optional) Toggle Include Spam & Trash to include drafts and messages from the Spam and Trash folders. Defaults to off.
  6. (Optional) Adjust Number of concurrent workers (between 2 and 10, default 5) to control how many requests the connector issues in parallel. Lower this value if you see frequent rate-limit errors.
  7. Click Set up source to test the connection and save the configuration.

Supported sync modes​

The Gmail source connector supports the following sync modes:

Sync modeSupported
Full Refresh | OverwriteYes
Full Refresh | AppendYes
Incremental | AppendYes
Incremental | Append + DedupedYes

Only the messages_details stream supports incremental sync. All other streams run in full refresh mode on every sync.

Streams​

StreamPrimary KeySync ModeDescription
profile(none)Full RefreshThe authenticated user's Gmail profile, including email address and history ID.
draftsidFull RefreshStub records (id, message.id, message.threadId) returned by users.drafts.list.
labelsidFull RefreshAll Gmail labels, including system labels (e.g. INBOX, SENT) and user-created labels.
labels_detailsidFull RefreshPer-label metadata such as message and thread counts. Substream of labels.
messagesidFull RefreshStub records (id, threadId) returned by users.messages.list.
messages_detailsidIncremental on internalDateFull message payloads, headers, snippet, and labels. Substream of messages.
threadsidFull RefreshStub records (id, historyId) returned by users.threads.list.
threads_detailsidFull RefreshPer-thread details and the messages in each thread. Substream of threads.

The messages_details cursor is the message's internalDate field — the Unix epoch in milliseconds when Gmail received the message. Other streams expose only id and threadId from the upstream list calls and have no record-level cursor field, so they run as full refresh.

When Start date is set, the connector applies the Gmail after:<epoch_seconds> search operator to the messages, drafts, and threads list requests so the API skips records older than that date.

Performance considerations​

The Gmail API enforces two simultaneous quota limits, measured in quota units:

Limit typeLimitError code
Per project rate limit1,200,000 quota units per minuterateLimitExceeded
Per user rate limit15,000 quota units per minute per useruserRateLimitExceeded

Each messages.list and messages.get call costs 5 units, and each threads.list and threads.get call costs 10 units. The messages_details and threads_details substreams issue one get call per parent record, so high-volume mailboxes consume quota quickly.

The connector retries 429 Too Many Requests and 403 quota-saturation errors with exponential backoff. If you see frequent rate-limit warnings in sync logs, lower the Number of concurrent workers setting.

Limitations & troubleshooting​

  • messages and threads are stub-only. The Gmail API's users.messages.list and users.threads.list endpoints return only {id, threadId} (or {id, historyId}) per record. To replicate the full message body, headers, or labels, sync the messages_details or threads_details substream alongside its parent.
  • Service account mailbox access requires domain-wide delegation. A service account without domain-wide delegation has no Gmail mailbox of its own to read. Configure domain-wide delegation in your Workspace admin console so the service account can impersonate Workspace users.
  • Read-only scope. This connector reads from Gmail only. The required scope is https://www.googleapis.com/auth/gmail.readonly. Granting broader Gmail scopes is not necessary and not recommended.

Configuration​

InputTypeDescriptionDefault Value
credentialsobjectAuthentication. Credentials for connecting to the Gmail API.
credentials.client_idstringClient ID. Enter your Google application's Client ID. See Google's documentation for more information.
credentials.client_secretstringClient Secret. Enter your Google application's Client Secret. See Google's documentation for more information.
credentials.client_refresh_tokenstringRefresh Token. Enter your Google application's refresh token. See Google's documentation for more information.
credentials.service_account_infostringService Account Information. The JSON key of the service account to use for authorization.
include_spam_and_trashbooleanInclude Spam & Trash. Include drafts/messages from SPAM and TRASH in the results. Defaults to false.false
num_workersintegerNumber of concurrent workers. Higher values result in faster syncs but may trigger rate limiting on lower-tier Gmail API quotas. Reduce this value if you see frequent rate-limit errors in sync logs.5
start_datestringUTC date and time in the format YYYY-MM-DDTHH:MM:SSZ. Only messages, threads, and drafts received on or after this date will be replicated. If unset, the full history is replicated.

Reference​

Config fields reference

Field
Type
Property name
object
credentials
boolean
include_spam_and_trash
integer
num_workers
string
start_date

Changelog​

Expand to review
VersionDatePull RequestSubject
0.1.12026-05-0476065Add OAuth flow with credentials wrapper, config migration, and Service Account auth
0.1.02026-04-2976431Add messages_details incremental sync, optional start_date server-side filtering on messages/drafts/threads, configurable concurrency via num_workers, and Gmail-aware rate-limit handling (429 + 403 quota-saturation)
0.0.522026-04-2877264Update dependencies
0.0.512026-04-2176616Update dependencies
0.0.502026-03-2475387Update dependencies
0.0.492026-03-1074532Update dependencies
0.0.482026-03-0374205Update dependencies
0.0.472026-02-1173300Revert OAuth authentication support
0.0.452026-02-1072593Update dependencies
0.0.442026-01-2071967Update dependencies
0.0.432026-01-1471388Update dependencies
0.0.422025-12-1870726Update dependencies
0.0.412025-11-2569871Update dependencies
0.0.402025-11-1869412Update dependencies
0.0.392025-10-2969004Update dependencies
0.0.382025-10-2168299Update dependencies
0.0.372025-10-1467999Update dependencies
0.0.362025-10-0767258Update dependencies
0.0.352025-09-3066299Update dependencies
0.0.342025-09-0966063Update dependencies
0.0.332025-08-2365371Update dependencies
0.0.322025-08-0964626Update dependencies
0.0.312025-08-0264194Update dependencies
0.0.302025-07-2663861Update dependencies
0.0.292025-07-1963463Update dependencies
0.0.282025-07-1263123Update dependencies
0.0.272025-07-0562624Update dependencies
0.0.262025-06-2862169Update dependencies
0.0.252025-06-2161834Update dependencies
0.0.242025-06-1461134Update dependencies
0.0.232025-05-2460608Update dependencies
0.0.222025-05-1059895Update dependencies
0.0.212025-05-0359276Update dependencies
0.0.202025-04-2658813Update dependencies
0.0.192025-04-1958184Update dependencies
0.0.182025-04-1257732Update dependencies
0.0.172025-04-0557214Update dependencies
0.0.162025-03-2955947Update dependencies
0.0.152025-03-0855265Update dependencies
0.0.142025-03-0154937Update dependencies
0.0.132025-02-2254417Update dependencies
0.0.122025-02-1553369Update dependencies
0.0.112025-02-0152831Update dependencies
0.0.102025-01-2552329Update dependencies
0.0.92025-01-1851700Update dependencies
0.0.82025-01-1151110Update dependencies
0.0.72024-12-2850536Update dependencies
0.0.62024-12-2150008Update dependencies
0.0.52024-12-1449474Update dependencies
0.0.42024-12-1249185Update dependencies
0.0.32024-10-2947852Update dependencies
0.0.22024-10-2847570Update dependencies
0.0.12024-10-09Initial release by @topefolorunso via Connector Builder
Was this page helpful?