Gmail API

The Gmail API integration allows you to read inbound emails, manage threads, and build email-based workflows. Perfect for support tickets, email parsing, and automated responses.

Setup

Configure OAuth 2.0 credentials in Google Cloud Console:

# .env
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=https://your-app.com/auth/google/callback

Reading emails

capabilityId: gmail-list-messages
provider:
  type: gmail
  operation: listMessages

inputs:
  query:
    type: string
    description: "Gmail search query"
  maxResults:
    type: number
    default: 10

outputs:
  messages:
    type: array
    items:
      type: object
      properties:
        id: string
        threadId: string
        snippet: string

Use cases

• Parse support emails and create tickets

• Extract attachments and process them

• Build email-to-task workflows

• Monitor specific email threads

• Sync threads into governed knowledge spaces with checkpointed deltas

Knowledge sync and mutation gates

Gmail supports the shared provider.delta.watch capability. Knowledge runtimes should persist provider cursor, watermark, dedupe, idempotency, replay, and tombstone state before acknowledging sync work. Outbound email sends should pass through knowledge mutation governance so dry-runs, approvals, audit evidence, and outbound-send gates are recorded.