Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Gmail

Scalekit connector
Open markdown

The Gmail connector lets your AI agent act in each user's Gmail account. Each user signs in to Gmail once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 48 tools.

Tools
48
What they doRead · write · destructive
21 · 19 · 821 read19 write8 destructive
Users sign in with
OAuth app
Your own Google app

What you can do

  • Read emails: fetch messages, threads, and attachments from any label or inbox
  • Send and reply: compose new emails and reply to existing threads on behalf of your users
  • Search messages: query Gmail with full search syntax to find emails by sender, subject, or content
  • Manage labels: apply, remove, and list labels to organize messages
  • Access contacts: look up contacts and people from the user’s address book

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Gmail connection

    In AgentKit > Connections, create a Gmail connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register a Google OAuth app

    Scalekit credentials aren't available for Gmail. In Google Cloud Console, enable the Gmail API and create an OAuth client ID for a web application, with the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Gmail connection.

    Console steps with screenshots

    Register your Scalekit environment with the Gmail connector so Scalekit handles the authentication flow and token lifecycle for you. The connection name you create will be used to identify and invoke the connection programmatically. Then complete the configuration in your application as follows:

    1. Set up auth redirects

      • In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find Gmail and click Create.

      • Copy the redirect URI. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.

        Copy redirect URI from Scalekit dashboard

      • Navigate to Google Cloud Console → APIs & Services → Credentials. Click + Create Credentials, then OAuth client ID. Choose Web application as the application type.

        Select Web application in Google Cloud Console

      • Under Authorized redirect URIs, click + Add URI, paste the redirect URI, and click Create.

        Add authorized redirect URI in Google Cloud Console

    2. Enable Gmail API

      • In Google Cloud Console, go to APIs & Services → Library. Search for “Gmail API” and click Enable.

        Enable Gmail API in Google Cloud Console

    3. Get client credentials

      Google provides your Client ID and Client Secret after you create the OAuth client ID in step 1.

    4. Add credentials in Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections and open the connection you created.

      • Enter your credentials:

        Add credentials for Gmail in Scalekit dashboard

      • Click Save.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'gmail'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Gmail:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'gmail_fetch_mails',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • gmail_fetch_mailsFetch emails from a connected Gmail account using search filters.Read-only

    Fetch Emails from Gmail

    Fetch emails from a connected Gmail account using search filters. Requires a valid Gmail OAuth2 connection.

    Inputs

    formatstring
    Format of the returned message.one of minimalfullrawmetadatadefault metadata
    include_spam_trashboolean
    Whether to fetch emails from spam and trash foldersdefault false
    label_idsarray
    Gmail label IDs to filter messages
    max_resultsinteger
    Maximum number of emails to fetch
    page_tokenstring
    Page token for pagination
    querystring
    Search query string using Gmail's search syntax (e.g., 'is:unread from:user@example.com')

    Also accepts schema_version and tool_version to pin a version.

  • gmail_get_attachment_by_idRetrieve a specific attachment from a Gmail message using the message ID and attachment ID.Read-only

    Fetch Attachment by Gmail ID

    Retrieve a specific attachment from a Gmail message using the message ID and attachment ID.

    Inputs

    attachment_idstringrequired
    Unique Gmail attachment ID
    message_idstringrequired
    Unique Gmail message ID that contains the attachment
    file_namestring
    Preferred filename to use when saving/returning the attachment

    Also accepts schema_version and tool_version to pin a version.

  • gmail_get_auto_forwardingGet the auto-forwarding settings for the authenticated Gmail account, showing whether incoming mail is automatically forwarded to another address and what happens to the local copy.Read-only

    Get Auto-Forwarding Settings

    Get the auto-forwarding settings for the authenticated Gmail account, showing whether incoming mail is automatically forwarded to another address and what happens to the local copy. Uses OAuth credentials.

    Inputs

    This tool takes no inputs.

  • gmail_get_contactsFetch a list of contacts from the connected Gmail account.Read-only

    Fetch Gmail Contacts

    Fetch a list of contacts from the connected Gmail account. Supports pagination and field filtering.

    Inputs

    max_resultsinteger
    Maximum number of contacts to fetch
    page_tokenstring
    Token to retrieve the next page of results
    person_fieldsarray
    Fields to include for each person

    Also accepts schema_version and tool_version to pin a version.

  • gmail_get_draftRetrieve a specific Gmail draft by draft ID.Read-only

    Get Gmail Draft

    Retrieve a specific Gmail draft by draft ID. Optionally control the format of the returned message content. Uses OAuth credentials.

    Inputs

    draft_idstringrequired
    The Gmail draft ID to retrieve. Obtain this from a list drafts operation. Example: 'r-1234567890123456789'.
    formatstring
    The format of the returned draft message. 'full' returns the parsed email with headers and body. 'minimal' returns only IDs and labels. 'raw' returns the full RFC 2822 message as a base64url string. 'metadata' returns headers only.one of minimalfullrawmetadata

    Also accepts schema_version and tool_version to pin a version.

  • gmail_get_filterGet details for a specific email filter in the authenticated Gmail account, including its criteria and actions.Read-only

    Get Email Filter

    Get details for a specific email filter in the authenticated Gmail account, including its criteria and actions. Use the List Email Filters tool to find valid filter IDs. Uses OAuth credentials.

    Inputs

    filter_idstringrequired
    The Gmail filter ID to retrieve. Obtain this from the List Email Filters tool. Example: 'ANe1BmiXxxxxxx'.

    Also accepts schema_version and tool_version to pin a version.

  • gmail_get_forwarding_addressGet the verification status of a single forwarding address configured for the authenticated Gmail account.Read-only

    Get Forwarding Address

    Get the verification status of a single forwarding address configured for the authenticated Gmail account. Uses OAuth credentials.

    Inputs

    forwarding_emailstringrequired
    The forwarding email address to look up. Use List Forwarding Addresses to find configured addresses.
  • gmail_get_labelGet details for a specific Gmail label, including its name, type, and visibility settings.Read-only

    Get Gmail Label

    Get details for a specific Gmail label, including its name, type, and visibility settings. Use the List Labels tool to find valid label IDs. Uses OAuth credentials.

    Inputs

    label_idstringrequired
    The Gmail label ID to retrieve. Use system labels such as 'INBOX', 'STARRED', 'IMPORTANT', or a custom label ID obtained from the List Labels tool. Example: 'Label_123'.

    Also accepts schema_version and tool_version to pin a version.

Workflows

Use Gmail response fields as returned

Response fields from Gmail tools use camelCase, such as threadId, messageId, and internalDate. Tool input parameters use the snake_case names shown in the Tool list, such as thread_id and message_id. Extract values with camelCase, then pass them with snake_case.

const fetchResponse = await actions.executeTool({
  connector: 'gmail',
  identifier: 'user_123',
  toolName: 'gmail_fetch_mails',
  toolInput: {
    query: 'is:unread',
    max_results: 5,
  },
});


const messages = Array.isArray(fetchResponse.data?.messages)
  ? fetchResponse.data.messages
  : [];
const threadId = typeof messages[0]?.threadId === 'string' ? messages[0].threadId : '';


if (threadId) {
  const threadResponse = await actions.executeTool({
    connector: 'gmail',
    identifier: 'user_123',
    toolName: 'gmail_get_thread_by_id',
    toolInput: {
      thread_id: threadId,
    },
  });
  console.log(threadResponse.data);
}
Proxy API call
const result = await actions.request({
  connectionName: 'gmail',
  identifier: 'user_123',
  path: '/gmail/v1/users/me/profile',
  method: 'GET',
});
console.log(result);
Google OAuth consent screen verification

Before you use your own Google OAuth credentials in production, understand what end users see on Google’s consent screen when they authorize a connected account.

Audience typeConsent screen behaviorWhen to use
InternalShows your App Name and logo from Branding settingsOnly users in your Google Workspace or Cloud Identity organization can authorize the connector
ExternalShows {env_name}.scalekit.dev until Google verifies your appAny user with a Google account can authorize the connector

Why External is required for most AgentKit connectors:

  • Internal restricts authorization to users in your Google Workspace or Cloud Identity organization. Users with @gmail.com or other Google accounts outside your organization cannot complete OAuth.
  • External is required when end users outside your organization authorize tool access through connected accounts.
  • Organization-managed OAuth clients follow the same rules as personal or developer OAuth clients. Switching to an org-owned client does not bypass Google verification.
  • Until Google completes verification of your External app, users see scalekit.dev on the consent screen. After verification, your App Name and logo appear.

During development:

  • Add Test users under APIs & Services → OAuth consent screen while publishing status is Testing.
  • On unverified apps, users can click Advanced → Go to app (unsafe) to proceed during testing.
  • Google Workspace admins may need to allowlist your OAuth client.

For Google’s verification requirements and timeline, refer to Google’s OAuth consent screen verification guide.

All 57 in Communication