Skip to main content

Gmail

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable Self-Managed EnterpriseAvailable PyAirbyte
Support Level
Marketplace
Connector Version
0.1.11 (last updated 10 hours ago)
Sync Success Rate
Low
Usage Rate
High
Data workers used
0.2 per sync (Learn more)
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.
  • A Gmail API scope that allows reading mail. Airbyte Cloud's OAuth flow requests https://www.googleapis.com/auth/gmail.modify, which includes read access. Self-managed OAuth clients and service accounts can grant the narrower https://www.googleapis.com/auth/gmail.readonly scope. In either case, the connector only issues read requests.
  • 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 a scope that grants read access to the mailbox.

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. The consent screen requests https://www.googleapis.com/auth/gmail.modify, so it asks you to let Airbyte read, compose, and send mail. The connector only issues read requests.

Sources that were authorized before connector version 0.1.11 keep the scope Google granted at consent time. You don't need to re-authenticate them.

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 a Gmail scope. Which scope you add depends on how you complete the flow:

    • If you obtain the refresh token yourself, add https://www.googleapis.com/auth/gmail.readonly.
    • If you register your OAuth client with your Airbyte instance and click Authenticate your account, add https://www.googleapis.com/auth/gmail.modify. Airbyte builds that consent URL from the connector, which requests gmail.modify, and the scope has to be configured on your consent screen.

    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.

On incremental syncs of messages_details, the connector still lists every message in the parent messages stream, then drops the messages whose internalDate predates the stored cursor. Incremental sync reduces what lands in your destination, not the API quota the list calls consume. If you leave Start date blank, the cursor starts at 2004-04-01, the date Gmail launched.

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.
  • The Cloud consent screen asks for more access than the connector uses. https://www.googleapis.com/auth/gmail.modify lets an app read, compose, and send mail, change labels, and trash messages. This connector only issues GET requests. To grant the narrower https://www.googleapis.com/auth/gmail.readonly scope instead, use your own OAuth client or a service account on a self-managed Airbyte instance.

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.

IP allow list​

If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

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.112026-08-0483308Use gmail.modify for Airbyte Cloud's managed OAuth flow; self-managed OAuth clients and service accounts continue to use gmail.readonly
0.1.102026-08-0483463Update dependencies
0.1.92026-07-2882922Update dependencies
0.1.82026-07-2182425Update dependencies
0.1.72026-07-1481816Update dependencies
0.1.62026-06-3081079Update dependencies
0.1.52026-06-2380468Update dependencies
0.1.42026-06-1679869Update dependencies
0.1.32026-06-0979310Update dependencies
0.1.22026-06-0278732Update dependencies
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.462026-02-1173273Add OAuth authentication support (reverted in 0.0.47)
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?