Gmail

Create a new bot

Scaffold a Next.js bot with the Gmail adapter using create-chat-sdk:

The generated app uses the Memory state adapter for local development. To add the adapter to an existing app, start at Install.

Install

Quick start

import { Chat } from "chat";
import { createGmailAdapter } from "@chat-adapter/gmail";
import { createRedisState } from "@chat-adapter/state-redis";

export const gmail = createGmailAdapter();

export const bot = new Chat({
  userName: "agent",
  adapters: { gmail },
  state: createRedisState(),
});

bot.onNewMention(async (thread) => {
  await thread.post("Received, I will review this email.");
});

Install Redis state and set REDIS_URL for this example. Shared persistent state preserves mailbox cursors and processed-message receipts across restarts.

import { after } from "next/server";
import { bot } from "@/lib/bot";

export async function POST(request: Request): Promise<Response> {
  return bot.webhooks.gmail(request, {
    waitUntil: (task) => after(() => task),
  });
}

Eligible incoming emails with the configured label are delivered as mentions. If several arrive in the same conversation during one sync, the adapter dispatches the newest and leaves earlier emails available through thread history. Sending a reply does not require an @mention in the email.

Platform setup

import {
  createGmailTokenProvider,
  listGmailLabels,
} from "@chat-adapter/gmail/api";

const token = createGmailTokenProvider({
  clientId: process.env.GMAIL_CLIENT_ID!,
  clientSecret: process.env.GMAIL_CLIENT_SECRET!,
  refreshToken: process.env.GMAIL_REFRESH_TOKEN!,
});

const result = await listGmailLabels({
  mailbox: process.env.GMAIL_MAILBOX!,
  token,
});

console.log(result.labels);

GMAIL_MAILBOX=agent@example.com
GMAIL_LABEL_ID=Label_123
GMAIL_CLIENT_ID=your-client-id
GMAIL_CLIENT_SECRET=your-client-secret
GMAIL_REFRESH_TOKEN=your-refresh-token
GMAIL_TOPIC_NAME=projects/your-project/topics/gmail-events
GMAIL_SUBSCRIPTION=projects/your-project/subscriptions/gmail-webhook
GMAIL_PUBSUB_AUDIENCE=https://your-domain.com/api/webhooks/gmail
GMAIL_PUBSUB_SERVICE_ACCOUNT_EMAIL=gmail-push@your-project.iam.gserviceaccount.com
REDIS_URL=redis://localhost:6379

import { bot, gmail } from "@/lib/bot";

await bot.initialize();
const watch = await gmail.watch();
console.log(watch.expiration);
await gmail.sync();

Configuration

Provide either clientId, clientSecret and refreshToken, or accessToken. Explicit configuration takes precedence over environment variables; explicit OAuth credentials also take precedence over GMAIL_ACCESS_TOKEN. Only the exact environment value true enables reply-all.

Environment variables

Webhooks

Built-in verification checks the Google-signed JWT, issuer, audience, expiration and push service-account email, then validates the wrapped payload and subscription. The root adapter also rejects notifications for a different mailbox.

A custom webhookVerifier replaces JWT authentication and takes precedence over audience and service-account configuration. It may read the request body. Falsy results or thrown errors reject the request; subscription, payload and mailbox checks still apply. Never use an always-true verifier on a public endpoint.

Replies and private delivery

Replies preserve the original subject, Gmail thread ID, In-Reply-To and References, matching Gmail's threading requirements. By default, the recipient is the original Reply-To, or From when absent.

Set replyAll: true to include the original To and Cc recipients, excluding the configured mailbox and duplicates. Bcc recipients are never copied. The adapter does not discover mailbox aliases or expand mailing lists.

thread.postEphemeral(userId, message, { fallbackToDM: true }) sends a permanent private email to the selected email address only, with no Cc or Bcc. It retains the subject and reply headers in an existing Gmail thread and adds a (private only) notice to the body. The result has usedFallback: true. Without the fallback, the adapter sends nothing.

Outside an active message handler, reply context comes from the latest incoming email. To return to a group conversation after a private exchange, use thread.reply(originalMessageId, message) with the original group message. Replies do not automatically quote earlier bodies or copy attachments.

For a new direct email, call gmail.openDM(address) and post to the returned route. Each post to that recipient route starts a new email with subject Private message; use the returned native thread ID for follow-ups. Calling openDM() alone sends nothing.

Standalone APIs

These entrypoints work without importing the Chat runtime:

Use the lower-level APIs when your application owns routing, sessions, approvals and retries:

import {
  createGmailDraft,
  createGmailTokenProvider,
  getGmailMessage,
} from "@chat-adapter/gmail/api";
import {
  extractGmailContinuation,
  parseGmailMessage,
} from "@chat-adapter/gmail/format";

const token = createGmailTokenProvider({
  clientId: process.env.GMAIL_CLIENT_ID!,
  clientSecret: process.env.GMAIL_CLIENT_SECRET!,
  refreshToken: process.env.GMAIL_REFRESH_TOKEN!,
});

const options = { mailbox: process.env.GMAIL_MAILBOX!, token };
const source = await getGmailMessage("native-message-id", options);
const email = await parseGmailMessage(source);
const continuation = extractGmailContinuation(email, options.mailbox);

const draft = await createGmailDraft({
  continuation,
  text: "Here is the proposed reply.",
}, options);

createGmailDraft() saves without sending. sendGmailMessage() sends immediately. Continuations preserve mailbox identity, recipients, subject and reply headers as serializable data. API options accept a token string or resolver, plus optional fetch and signal.

Native events and history

createGmailWebhookVerifier() verifies authentication and the configured subscription, returning the decoded notification and original wrapped Pub/Sub envelope. It does not read messages, store a cursor or dispatch a Chat event. Check emailAddress against your authorized mailbox before any reads or routing. parseGmailNotification() only parses; it does not authenticate.

listGmailHistory({ startHistoryId, pageToken }, options) returns one page of additions, deletions and label changes without fetching email bodies. History can include sent and received mail. Use the specific change arrays instead of also processing the general messages references, which can duplicate them.

Keep history IDs and page tokens as opaque strings. Follow every page and save the final history cursor only after processing is durable. The notification's historyId is a wake-up signal, not a cursor to save before processing. History order is not email-date order.

listGmailMessages() supports search, label filtering and pagination. getGmailThread() returns ordered message pointers, not hydrated messages. Call getGmailMessage() and parseGmailMessage() only for the emails you need.

With standalone APIs, your application owns mailbox serialization, deduplication, cursor persistence, renewal and expired-history recovery. A 404 for an old history cursor requires a full sync. Finish processing or durably enqueue the verified event before acknowledging Pub/Sub; do not start untracked background work and return success.

Thread IDs

gmail:{mailbox}:{threadId}       # Gmail conversation
gmail:{mailbox}:dm:{recipient}   # recipient route returned by openDM()

Examples: gmail:YWdlbnRAZXhhbXBsZS5jb20:18c2f0a1b2c3d4e5, gmail:YWdlbnRAZXhhbXBsZS5jb20:dm:YWxleEBleGFtcGxlLmNvbQ.

mailbox and recipient are base64url-encoded email addresses. threadId is the native Gmail thread ID. The channel ID is gmail:{mailbox}, so every thread in a mailbox belongs to one channel.

Limitations

• The root adapter uses durable receipts to suppress already-handled or superseded emails. When history expires, it scans the current intake label, which can include older emails never previously handled.
• Sent mail, drafts, spam and trash do not trigger handoffs. Label eligibility is checked before loading bodies and again before dispatch.
• Oversized or malformed emails and failed handler handoffs are recorded and logged without automatic replay. An acknowledged notification means its changes were accounted for, not that every handler succeeded. Inspect logs and reconcile side effects before retrying.
• Email sending and state writes are not transactional. A failed request can have an unknown send outcome; check the mailbox before sending again. API acceptance does not prove delivery to the recipient.
• Streamed text is buffered into one email, not live-edited. The adapter limits buffered stream text to 1 MiB and raw incoming or composed outgoing MIME to 25 MiB. These are adapter limits, not Gmail quotas.
• Sent messages cannot be edited or recalled through the adapter. Cards render as plain text; buttons do not produce actions.
• bot.shutdown() does not unregister the watch. For permanent disconnection, stop scheduled jobs and use stopGmailMailbox() from /api. It stops notifications for the mailbox, not only this label, and does not revoke OAuth consent or erase state.

Feature support