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)
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

All Google integrations (Drive, Gmail, Calendar) share the same GOOGLE_OAUTH2 credential. Install any of them first — the others will reuse it.

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.

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.

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 Doorkeeper 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.

What's Next​