Gmail

Authentication

Type	Default	Details
`oauth_2`	✅	Google OAuth 2.0 with `offline` access for refresh tokens

Gmail requires Google OAuth with these scopes:

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.modify

The access_type: "offline" parameter ensures refresh tokens are issued.

Endpoints

Path	Risk	Description
`messages.list`	read	List Gmail messages matching a query.
`messages.get`	read	Fetch a single message by id.
`messages.send`	write	Send an email (raw RFC-2822 base64url body).
`messages.trash`	write	Move a message to trash (recoverable).
`messages.untrash`	write	Restore a message from trash.
`messages.delete`	destructive	Permanently delete a message.
`labels.list`	read	List labels.

`messages.list`

List messages with optional query filtering.

Input:

Field	Type	Description
`q`	string	Gmail search query (e.g. `from:alice@example.com`)
`maxResults`	number	Max results per page
`pageToken`	string	Pagination token
`labelIds`	string[]	Filter by label IDs

Output: GmailMessageList — { messages?: Array<{ id: string; threadId: string }>; nextPageToken?: string; resultSizeEstimate?: number }

`messages.get`

Fetch a single message by ID.

Input:

Field	Type	Required	Description
`id`	string	✅	Message ID
`format`	enum		`full` (default), `metadata`, `minimal`, `raw`

Output: GmailMessage

`messages.send`

Send an email. The body must be a raw RFC-2822 message, base64url-encoded.

Input:

Field	Type	Required	Description
`raw`	string	✅	Base64url-encoded RFC-2822 message

Output: GmailMessage

`messages.trash`

Move a message to trash.

Input:

Field	Type	Required	Description
`id`	string	✅	Message ID

Output: GmailMessage

`messages.untrash`

Restore a message from trash.

Input:

Field	Type	Required	Description
`id`	string	✅	Message ID

Output: GmailMessage

`messages.delete`

Permanently delete a message (irreversible).

Input:

Field	Type	Required	Description
`id`	string	✅	Message ID

Output: { ok: boolean }

`labels.list`

List all labels in the user's mailbox.

Input: None

Output: { labels?: GmailLabel[] }

Usage

import { createFabric } from "@fabricorg/integrations";
import { gmail } from "@fabricorg/integrations/plugins";

const fabric = createFabric({
  plugins: [gmail({ accessToken: process.env.GMAIL_ACCESS_TOKEN })],
});

// List recent emails
const { messages } = await fabric.gmail.api.messages.list({ q: "is:unread", maxResults: 10 });

// Get a message
const msg = await fabric.gmail.api.messages.get({ id: messages[0].id, format: "full" });

// Send an email (using a helper to build the raw message)
const raw = buildRawMessage({ to: "alice@example.com", subject: "Hello", body: "..." });
await fabric.gmail.api.messages.send({ raw });

Webhooks

Gmail uses Google Pub/Sub push notifications rather than direct webhooks. The portal's Pub/Sub bridge invokes messages.list with historyId when notifications arrive.

Types

interface GmailMessage {
  id: string;
  threadId?: string;
  labelIds?: string[];
  snippet?: string;
  historyId?: string;
  internalDate?: string;
  payload?: unknown;
}

interface GmailLabel {
  id: string;
  name: string;
  type: "system" | "user";
}

Gmail

On this page