Skip to main content

Gmail

Connect Gmail to ORQO so that agents can search, read, send, and manage emails through MCP tools.

CategoryCommunication
CapabilitiesMCP tools, receive (via Pub/Sub triggers), document source (email sync)
Adapter path/gmail
Auth methodOAuth 2.0 (shared Google credential)
info

Gmail provides MCP tools for agents to interact with Gmail programmatically — searching inboxes, reading messages, composing emails, and managing labels. It also supports inbound email triggers via Google Cloud Pub/Sub for event-driven workflows.

Prerequisites​

  • A Google account with Gmail access
  • A Google Cloud project with the Gmail API enabled
  • OAuth 2.0 credentials (client ID and client secret)
  • Access to the ORQO Settings area

Setup​

1. Set Up Google Cloud Credentials​

  1. Go to the Google Cloud Console.
  2. Create a project (or select an existing one).
  3. Enable the Gmail API under APIs & Services > Library.
  4. Navigate to APIs & Services > Credentials and create OAuth 2.0 Client ID credentials (or reuse credentials from another Google integration).
  5. Set the redirect URI to the OAuth Callback URL shown on the app's detail card in ORQO.
  6. Note the client ID and client secret.

2. Install the Gmail App in ORQO​

  1. Navigate to Settings > Integrations in ORQO.
  2. Switch to the Catalog tab and find Gmail.
  3. Click the card to view details, then click Install.

Gmail uses the shared Google OAuth credential:

CredentialTypeDescription
GOOGLE_OAUTH2oauth2OAuth 2.0 credentials (client ID, client secret, tokens)

Create the credential in Settings > Credentials with your Google Cloud client ID and client secret, then assign it to the Gmail app. If you already have a GOOGLE_OAUTH2 credential from another Google integration (Drive, Calendar), assign that same credential — no need to create a new one.

Shared Google credential

For a single Google account, all Google integrations (Drive, Gmail, Calendar) can share the same GOOGLE_OAUTH2 credential — install any of them first and the others will reuse it. To connect a different Google account, install Gmail again as a separate, named instance with its own credential (see Connect Multiple Mailboxes below).

4. Authorize via OAuth​

  1. Click Connect with OAuth on the Gmail app card.
  2. Google's consent screen shows the requested Gmail permissions.
  3. Approve access. ORQO stores the tokens and refreshes them automatically.

Because all Google integrations use incremental authorization, authorizing Gmail adds the Gmail scope to your existing Google token — it does not revoke Drive or Calendar access.

5. Verify the Connection​

Click Verify on the Gmail app card. This tests the connection and discovers the available MCP tools.

Connect Multiple Mailboxes​

You can install Gmail more than once to connect several mailboxes to the same organization — for example a personal inbox and a shared sales inbox. When you install Gmail again, give the new install a distinct name (such as "Gmail – Personal" or "Sales Inbox") so you can tell the mailboxes apart.

Each Gmail install gets its own credential and is authorized independently with Connect with OAuth, so you sign in to each mailbox separately. In a workflow, different agents can use different mailboxes — their tools are kept separate automatically.

See Connect multiple accounts of the same service for the full walkthrough.

Available Tools​

ToolDescription
gmail_searchSearch emails using Gmail query syntax (same as the Gmail search bar)
gmail_read_messageRead a full email — subject, from, to, date, body
gmail_sendCompose and send a new email
gmail_replyReply to an existing email thread (supports reply-all)
gmail_create_draftSave an email as a draft without sending
gmail_list_labelsList all Gmail labels (Inbox, Sent, custom labels)
gmail_modify_labelsAdd or remove labels from an email (also used to archive by removing INBOX, or mark read by removing UNREAD)
gmail_create_labelCreate a new custom Gmail label (idempotent — returns existing label if name matches)

These tools are discovered automatically when the app is verified and can be assigned to agents via Skills.

Search Query Examples​

The gmail_search tool accepts the same query syntax as Gmail's search bar:

QueryWhat it finds
from:alice@example.comEmails from Alice
subject:quarterly reportEmails with "quarterly report" in the subject
is:unreadUnread emails
newer_than:2dEmails from the last 2 days
has:attachment filename:pdfEmails with PDF attachments
from:alice subject:report newer_than:7dCombined filters

Receive Capability (Triggers)​

Gmail can receive inbound emails as trigger events via Google Cloud Pub/Sub. This lets you build workflows that react to incoming emails — triage, classification, auto-response, or routing to the right team.

How It Works​

Gmail Inbox
 +-- new email arrives
 |
 v
Google Cloud Pub/Sub
 +-- topic: projects/{project}/topics/gmail-push
 +-- subscription: push to ORQO webhook endpoint
 |
 v
ORQO Webhooks Controller
 +-- parse-inbound -> { event_type: "email_received", ... }
 +-- matches Trigger with event_type "email_received"
 |
 v
Workflow runs with email content as initial message

Prerequisites​

  1. A Google Cloud Pub/Sub topic in your Google Cloud project.
  2. A push subscription on that topic, pointing to ORQO's webhook URL for the Gmail app.
  3. A Gmail watch registered via the Gmail API, directing push notifications to your Pub/Sub topic.
Gmail Watch Expiry

Gmail watches expire after 7 days. You must renew the watch periodically (via a cron job, Cloud Scheduler, or manual renewal). If the watch expires, inbound email notifications stop silently.

Setting Up a Trigger​

  1. Create a Trigger on a workflow and set the event source to the Gmail app.
  2. Set the event type to email_received.
  3. When an email arrives, the trigger fires and the workflow receives the email body, subject, sender, and metadata.

Event Payload​

The Gmail adapter parses inbound Pub/Sub notifications into this format:

FieldValue
event_typeemail_received
senderThe email's From address
messageThe email body (plain text, extracted from the message)
metadata.subjectThe email subject line
metadata.gmail_message_idThe Gmail message ID (for use with gmail_read_message or gmail_modify_labels)
dedup_keyThe Gmail message ID (prevents duplicate processing on webhook retries)
is_bottrue if the message was sent by the platform (has SENT label without INBOX)

Example Use Cases​

  • Email triage — classify inbound emails by topic, urgency, or sender and apply labels automatically.
  • Auto-response — detect specific patterns (support requests, meeting invitations) and draft or send replies.
  • CRM routing — extract contact info from emails and create records in external systems.
  • Digest generation — aggregate emails matching a query into a daily summary artifact.

Sync Emails to Documents (Knowledge Graph)​

Beyond live triggers, Gmail can act as a document source: ORQO periodically pulls the emails carrying a chosen label into a project's document library, converts each to Markdown, and — when the project's Knowledge Graph is enabled — classifies them into the graph. This turns correspondence into a searchable knowledge base: investor updates, client threads, vendor docs, or your own sent decisions.

Resource Path = a Gmail label​

When you connect Gmail as a source (Project → Documents → Connect Source → Gmail), the Resource Path is a Gmail label name — not a folder or a search. Only emails carrying that label are synced.

  • Create a label in Gmail (for example KG), apply it to the emails you want, then enter KG as the Resource Path.
  • To test immediately with no setup, use SENT — your own outgoing mail.

Allowed labels: any custom label, plus SENT, STARRED, and IMPORTANT.

Rejected labels: INBOX, SPAM, TRASH, DRAFT, UNREAD, and the CATEGORY_* buckets — these are too broad and would flood your library. Point the source at a deliberate label instead.

One label, both directions

A single label spans incoming and sent mail — labeling a sent email pulls it in alongside received ones. You can even build a workflow that reads your inbox and applies the KG label automatically (using gmail_modify_labels), so curation happens hands-free.

Options​

FieldFor Gmail
Resource PathA Gmail label name (e.g. KG, SENT)
Target FolderWhere synced emails land in the document library (e.g. emails)
Sync EveryHow often ORQO checks for newly-labeled emails
File FilterOptional Gmail search query to narrow the label (e.g. has:attachment) — not a filename glob

How it syncs​

  • One document per email, rendered as Markdown — a header block (From / To / Date / Thread) followed by the body.
  • A newly-labeled email — even an old one — is picked up on the next sync, so labeling is your per-message on/off switch.
  • Removing the label stops future syncs of that email; the document already in your library is kept.

Platform-Specific Behavior​

  • OAuth 2.0 with incremental scopes — Gmail uses the gmail.modify scope. When authorized alongside Google Drive or Calendar, scopes are merged into a single token.
  • Thread-aware replies — The gmail_reply tool preserves thread context, so replies appear correctly in the recipient's inbox as part of the conversation.
  • Receive via Pub/Sub, not SMTP — Gmail receives inbound emails through Google Cloud Pub/Sub push notifications, not SMTP. For SMTP-based email delivery through Chief of Staff channels, use the Email app instead.
  • Feedback loop prevention — When agents send emails via gmail_send or gmail_reply, the adapter detects outbound messages (SENT label without INBOX) and sets is_bot: true to prevent trigger loops.

Sending Files (Outbound)​

Chief of Staff can attach files to the emails it sends — documents and artifacts from a project's library, or files shared earlier in the conversation. Any file type can be attached as a standard email attachment, subject to Gmail's overall message size limit (~25 MB).

What's Next​