Skip to main content

Gmail

Gmail is Google's email service, providing secure, reliable email communication with powerful search, organization, and filtering capabilities. The Gmail API enables programmatic access to Gmail mailbox data, including messages, labels, drafts, and attachments, allowing applications to read, send, and manage email on behalf of users.

Gmail icon

Power end-to-end data operations for your Gmail API with Nexla. Our bi-directional Gmail connector is purpose-built for Gmail, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Gmail or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Gmail workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

  • Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
  • Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
  • API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
  • Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites​

Before creating a Gmail credential in Nexla, ensure the following requirements are met:

Google Account​

An active Google account with access to the Gmail mailbox you want to connect is required. The account must have Gmail enabled and accessible.

Required Permissions​

The Nexla Gmail connector uses OAuth 2.0 to authenticate with the Gmail API. During the authorization process, you will be prompted to grant the following access scopes:

  • gmail.readonly -- Allows Nexla to read messages, labels, and attachments from your Gmail account.
  • gmail.send -- Allows Nexla to send messages and drafts on your behalf.
  • gmail.modify -- Allows Nexla to modify message labels (such as marking messages as read or archiving them) and manage drafts.

These scopes are requested together during the OAuth authorization flow. You must approve all requested scopes for full connector functionality. If you only need to read data from Gmail, the connector will still function with limited permissions, but destination endpoints (such as sending messages or modifying labels) may not be available.

Google Workspace Considerations​

If you are using a Google Workspace (formerly G Suite) account, your organization's administrator may need to approve third-party application access. If you encounter an authorization error during the OAuth flow, contact your Google Workspace administrator to ensure that the Nexla application is permitted to access Gmail data. For additional details, refer to Google's documentation on controlling third-party app access.

Authenticate​

Create a credential in Nexla​

  1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

  2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

  3. Click the Authorize button to initiate the OAuth 2.0 authorization flow. A new browser window will open, directing you to the Google sign-in page.

  4. Sign in with the Google account that has access to the Gmail mailbox you want to connect. If you are already signed in, select the appropriate account from the list.

  5. Review the permissions that Nexla is requesting, and click Allow to grant access. Google will redirect you back to Nexla once authorization is complete.

    The OAuth authorization flow is managed entirely by Google. Nexla does not have access to your Google account password. The authorization grants Nexla a secure token that allows it to access Gmail data on your behalf, and this access can be revoked at any time from your Google Account permissions page.

  6. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.

Use as a data source​

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Gmail connector tile, then select the credential that will be used to connect to the Gmail instance, and click Next; or, create a new Gmail credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Gmail endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

List Messages

Retrieves a list of messages matching a specified search query, along with the full content of each message. This is the primary endpoint for ingesting email data from Gmail and is ideal for monitoring inbox activity, processing incoming messages, or extracting email content for analysis.

  • In the User ID field, enter the Gmail user ID whose messages should be retrieved. The default value is me, which refers to the authenticated user's mailbox. In most cases, this default is appropriate and does not need to be changed.
  • In the Search Query field, enter a Gmail search query to filter which messages are retrieved. The default value is is:unread, which retrieves only unread messages. Gmail search queries use the same syntax as the Gmail search box. Common examples include: is:unread (unread messages), from:user@example.com (messages from a specific sender), subject:invoice (messages with a keyword in the subject), has:attachment (messages with attachments), after:2025/01/01 before:2025/12/31 (messages within a date range), and label:important (messages with a specific label).

This endpoint uses a two-step chained API call. First, it retrieves a list of message IDs matching the search query, then it fetches the full content of each message. Pagination is handled automatically for large result sets. For the complete list of supported search operators, refer to the Gmail search operators documentation.

Get Message Details

Retrieves the full content of a specific message, including headers, body, and metadata. Use this endpoint when you need to fetch detailed information about a known message by its ID.

  • In the User ID field, enter the Gmail user ID whose message should be retrieved. The default value is me, which refers to the authenticated user's mailbox.
  • In the Message ID field, enter the unique identifier of the message to retrieve. This field is required. Message IDs can be obtained from the "List Messages" endpoint or from other Gmail API responses.

The message ID is a unique, immutable identifier assigned by Gmail. It differs from the message's RFC 822 Message-ID header. For additional details, refer to the Gmail API messages.get documentation.

Get Attachment

Retrieves a specific attachment from a message. Use this endpoint when you need to extract file attachments from email messages for processing or storage.

  • In the User ID field, enter the Gmail user ID. The default value is me, which refers to the authenticated user's mailbox.
  • In the Message ID field, enter the unique identifier of the message that contains the attachment. This field is required.
  • In the Attachment ID field, enter the unique identifier of the attachment to retrieve. This field is required. Attachment IDs can be found in the message payload from the "Get Message Details" or "List Messages" endpoints, within the body.attachmentId field of message parts that represent attachments.

Attachment data is returned as a base64url-encoded string in the response. For additional details, refer to the Gmail API attachments.get documentation.

List Labels

Retrieves a list of all labels in the user's mailbox, including both system labels (such as INBOX, SENT, TRASH) and user-created labels. Use this endpoint to discover available labels for filtering messages or to audit label organization.

  • In the User ID field, enter the Gmail user ID whose labels should be retrieved. The default value is me, which refers to the authenticated user's mailbox.

The response includes both system labels (such as INBOX, SENT, SPAM, TRASH, STARRED) and custom labels created by the user. Label IDs returned by this endpoint can be used with the "Modify Message Labels" destination endpoint. For additional details, refer to the Gmail API labels.list documentation.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration​

Gmail data sources can also be manually configured to ingest data from any valid Gmail API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

Gmail API endpoints follow the base URL pattern https://gmail.googleapis.com/gmail/v1/users/{userId}/{resource}, where userId is typically me for the authenticated user. Date/time macros are useful for filtering messages by date using the q parameter with Gmail search operators such as after: and before:. For the List Messages endpoint, the messages array is located at $.messages[*] in the JSON response; for endpoints that return a single message object, use $ to capture the entire response. For a complete list of available endpoints, refer to the Gmail API REST reference.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Gmail data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination​

Click the + icon on the Nexset that will be sent to the Gmail destination, and select the Send to Destination option from the menu. Select the Gmail connector from the list of available destination connectors, then select the credential that will be used to connect to the Gmail organization, and click Next; or, create a new Gmail credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Gmail endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

Modify Message Labels

Adds or removes labels from a specific message. Use this endpoint to organize messages by applying labels (such as STARRED or custom labels) or removing labels (such as UNREAD to mark messages as read).

  • In the User ID field, enter the Gmail user ID. The default value is me, which refers to the authenticated user's mailbox.
  • In the Message ID field, enter the unique identifier of the message whose labels should be modified. This field is required.
  • In the Labels to Add field, enter a JSON array of label IDs to apply to the message (e.g., ["STARRED"]). The default value is an empty array [].
  • In the Labels to Remove field, enter a JSON array of label IDs to remove from the message (e.g., ["UNREAD"]). The default value is an empty array [].

Use the "List Labels" source endpoint to retrieve available label IDs for your mailbox. Common system label IDs include INBOX, UNREAD, STARRED, IMPORTANT, SPAM, and TRASH. For additional details, refer to the Gmail API messages.modify documentation.

Create Draft

Creates a new email draft in the user's mailbox. Use this endpoint when you need to prepare messages for review before sending, or to programmatically create drafts that can be sent later.

  • In the User ID field, enter the Gmail user ID. The default value is me, which refers to the authenticated user's mailbox.
  • In the Raw Message (Base64Url) field, enter the complete email message content encoded as a base64url string. The raw message must be a valid RFC 822 email, including headers such as To, From, Subject, and the message body. This field is required.

The raw message must be base64url-encoded (not standard base64). Base64url encoding replaces + with - and / with _, and omits padding characters. For additional details on constructing RFC 822 messages, refer to the Gmail API drafts.create documentation.

Send Message

Sends an email message directly to the specified recipients. Use this endpoint when you need to send messages programmatically, such as automated notifications, reports, or transactional emails.

  • In the User ID field, enter the Gmail user ID. The default value is me, which refers to the authenticated user's mailbox.
  • In the Raw Message (Base64Url) field, enter the complete email message content encoded as a base64url string. The raw message must be a valid RFC 822 email, including headers such as To, From, Subject, and the message body. This field is required.

Messages sent through this endpoint will appear in the user's Sent Mail. The raw message must be base64url-encoded and include all required RFC 822 headers. For additional details, refer to the Gmail API messages.send documentation.

Send Draft

Sends an existing draft to its intended recipients. Use this endpoint when drafts have been created (either manually or via the "Create Draft" endpoint) and are ready to be delivered.

  • In the User ID field, enter the Gmail user ID. The default value is me, which refers to the authenticated user's mailbox.
  • In the Draft ID field, enter the unique identifier of the draft to send. This field is required. Draft IDs can be obtained from the Gmail API drafts.list endpoint or from the response of a previous "Create Draft" call.

Once a draft is sent, it is removed from the Drafts folder and the sent message appears in the Sent Mail folder. This action cannot be undone. For additional details, refer to the Gmail API drafts.send documentation.

Delete Message

Immediately and permanently deletes a specific message. Use this endpoint with caution, as deleted messages cannot be recovered.

  • In the User ID field, enter the Gmail user ID. The default value is me, which refers to the authenticated user's mailbox.
  • In the Message ID field, enter the unique identifier of the message to permanently delete. This field is required.

⚠ Danger: This operation is irreversible. The message is permanently deleted and cannot be recovered from Trash. To move a message to Trash instead (which allows recovery), use the "Modify Message Labels" endpoint and add the TRASH label.

For additional details, refer to the Gmail API messages.delete documentation.

Manual configuration​

Gmail destinations can also be manually configured to send data to any valid Gmail API endpoint. Using manual configuration, you can also configure Nexla to automatically send the response received from the Gmail API after each call to a new Nexla webhook data source. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

Gmail API endpoints follow the base URL pattern https://gmail.googleapis.com/gmail/v1/users/{userId}/{resource}. For update/upsert operations, include the ID of the object to be updated at the end of the URL.

Save & activate​

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured Gmail endpoint, open the destination resource menu, and select Activate.

The Nexset data will not be sent to Gmail until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.