Skip to main content

Gmail

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Connector type (beta)
Available Data replicationAvailable Agent(learn more)
Support Level
Marketplace
Connector Version
0.1.20 (last updated 4 days 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. An OAuth client you manage yourself 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 an OAuth 2.0 client and refresh token.

Setup guide​

Step 1: Set up authentication​

The Gmail source connector offers two authentication methods: OAuth and Service Account Key. Use OAuth. Service Account Key authentication can't currently read a 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.

note

If you configured this source before version 0.1.1, Client ID, Client Secret, and Refresh Token were top-level fields. The connector moves them into the nested Authentication object automatically the first time it runs on a newer version, as long as all three values are present. You don't need to re-enter them. Sources that already use the nested OAuth or Service Account Key configuration aren't changed.

Service Account Key for Airbyte Open Source​

warning

Service Account Key authentication can't currently read a mailbox. To read a user's mailbox, Google requires the token request to name the user to impersonate in the sub claim, and only applies domain-wide delegation when that claim is set. The connector doesn't set sub and has no field for the user to impersonate, so Google issues a token for the service account itself. A service account has no Gmail mailbox, so the connection test and syncs fail with Precondition check failed, whether or not domain-wide delegation is configured. Use OAuth instead.

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 — Not currently usable. The connector authenticates as the service account itself, which has no mailbox. Use OAuth instead.
  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. The connection test reads the authenticated user's Gmail profile.

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 limit6,000 quota units per minute per useruserRateLimitExceeded

Each threads.get call costs 40 units, messages.get 20, threads.list 10, messages.list and drafts.list 5, and labels and profile calls 1. The messages_details and threads_details substreams issue one get call per parent record, so high-volume mailboxes consume quota quickly.

These are the quotas for Google Cloud projects created on or after May 1, 2026. Projects that used the Gmail API between November 2025 and April 2026 keep their previous quotas: 15,000 units per minute per user, with messages.get and messages.list at 5 units and threads.get and threads.list at 10. Because the limit depends on the project, the connector doesn't throttle its calls up front and relies on Gmail's rate-limit responses instead.

The connector retries 429 Too Many Requests and 403 quota-saturation errors with backoff, up to 10 times over roughly 10 to 13 minutes. After a 429, every request waits up to a minute for the current quota window to clear. 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 keys can't read a mailbox. The connector doesn't set the sub claim that Google requires for a service account to impersonate a user, so the token belongs to the service account, which has no mailbox. Domain-wide delegation doesn't change this. Use OAuth instead.
  • Precondition check failed. The authenticated account has no Gmail mailbox. Either you used Service Account Key authentication, or you authorized a Google Workspace user who doesn't have Gmail enabled. Authenticate with OAuth as the user whose mailbox you want to sync.
  • The Gmail API isn't enabled. On Airbyte Open Source with your own OAuth client, the connector fails with a configuration error until you enable the Gmail API in the Google Cloud project that owns the client.
  • The authorized account lacks the required scope. If Gmail returns insufficientPermissions, re-authenticate and grant https://www.googleapis.com/auth/gmail.readonly (a refresh token you obtained yourself) or https://www.googleapis.com/auth/gmail.modify (the Authenticate your account flow).
  • Your Workspace administrator has disabled Gmail apps. If Gmail returns domainPolicy, ask your Google Workspace administrator to allow Gmail API access for the app, then retry.
  • 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 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.212026-10-1388403Check connection via profile and retry rate limits; add actionable Gmail API errors, API budget and missing schema fields
0.1.202026-10-1388635Update dependencies
0.1.192026-10-0687854Update dependencies
0.1.182026-09-2987179Update dependencies
0.1.172026-09-2286632Update dependencies
0.1.162026-09-1586066Update dependencies
0.1.152026-09-1185800Fix config migration copying empty or incomplete legacy OAuth fields into nested credentials
0.1.142026-09-0885497Update dependencies
0.1.132026-08-1884554Update dependencies
0.1.122026-08-1183951Update dependencies
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?