Gmail

Google Workspace or Gmail through the Gmail API, with optional Pub/Sub push.

Install

Terminal

npx shadcn@latest add @tendkit/channel-gmail

It lands in lib/support/channels/. Import gmailChannel from there.

Set up

Enable the Gmail API
In Google Cloud, enable the Gmail API and create a service account with a JSON key.
Delegate access (Google Workspace)
Admin console → Security → API controls → Domain-wide delegation: add the service account's client id with the scope https://www.googleapis.com/auth/gmail.modify. It can take up to 24 hours.
Or, a single Gmail account
Create an OAuth client, run the consent flow once with access_type=offline&prompt=consent and scope gmail.modify, and pass the refresh token. Apps left in Testing get refresh tokens that expire after 7 days.
Run the schedule, optionally push
runScheduled() polls the mailbox history. For replies within seconds, create a Pub/Sub topic, grant gmail-api-push@system.gserviceaccount.com the Publisher role, add an authenticated push subscription to the channel's webhook URL and pass pubsub. The watch is renewed daily.

Configure

lib/support/index.ts

gmailChannel({
  id: "email",
  mailbox: "support@acme.com",
  auth: {
    serviceAccount: {
      clientEmail: process.env.GOOGLE_CLIENT_EMAIL!,
      privateKey: process.env.GOOGLE_PRIVATE_KEY!,
    },
  },
  pubsub: { topic: "projects/acme/topics/gmail-support" },
})

Options

Name	Type	Description
`id`*	`string`	Stable channel id, stored on every ticket and used in the webhook URL. Never change it.
`mailbox`*	`string`	The mailbox customers write to.
`auth`*	`{ serviceAccount } \| { oauth }`	A service account with domain-wide delegation, or an OAuth refresh token.
`replyAddress`	`string`	An extra address that routes to this mailbox, used for the ticket token.
`pubsub`	`{ topic, audience?, serviceAccountEmail? }`	Push notifications. Without it the mailbox is polled only.
`fetch / baseUrl`		For tests and proxies.

Behaviour

Replies your team writes in Gmail show up on the ticket.
Each sync fetches up to 100 messages; the rest come next time.

PreviousMicrosoft 365 NextSMTP and IMAP