OpenAPI Marketplace · Email

Gmail Inbox & Send

Name: Gmail Inbox & Send
Author: vx.ai

v1.0.0 · 11 endpoints · 0 connections · shared by vx.ai

Lets an agent work a Gmail inbox: search and read messages and threads, draft replies, send email, and label, archive or mark messages as read. Based on the Google Gmail API specification.

Connect this API to an AI agent Browse all specs

What you can do with Gmail Inbox & Send via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

Method	Path	Operation	Description
GET	`/gmail/v1/users/{userId}/profile`	getProfile	Get the mailbox owner's email address and message counts
GET	`/gmail/v1/users/{userId}/messages`	listMessages	Search messages with Gmail search syntax (returns ids)
GET	`/gmail/v1/users/{userId}/messages/{id}`	getMessage	Read one message (headers, body, labels)
GET	`/gmail/v1/users/{userId}/threads`	listThreads	Search conversation threads with Gmail search syntax
GET	`/gmail/v1/users/{userId}/threads/{id}`	getThread	Read a whole conversation thread
GET	`/gmail/v1/users/{userId}/labels`	listLabels	List the mailbox's labels and their ids
GET	`/gmail/v1/users/{userId}/drafts`	listDrafts	List saved drafts
POST	`/gmail/v1/users/{userId}/drafts`	createDraft	Save a draft email (optionally as a reply in a thread)
POST	`/gmail/v1/users/{userId}/drafts/send`	sendDraft	Send an existing draft
POST	`/gmail/v1/users/{userId}/messages/send`	sendMessage	Send an email immediately
POST	`/gmail/v1/users/{userId}/messages/{id}/modify`	modifyMessageLabels	Add or remove labels on a message (mark read, archive, star)

Authentication

googleOAuth

OAuth 2.0

Scopes: https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.compose https://www.googleapis.com/auth/gmail.modify

Google OAuth 2.0 (authorization code, delegated access to the signed-in user's mailbox).

How to get a credential

In the Google Cloud console, create or pick a project and enable the Gmail API (APIs & Services > Library).
Configure the OAuth consent screen (Internal for Workspace-only use, or External with test users) and add the scopes below.
Create an OAuth client ID of type Web application and add the VX Agents redirect URI shown in the credential form.
Paste the client ID and secret into the VX Agents credential, then sign in with the Google account whose mailbox the agent should use.

Permissions used

Scope	Operations
`gmail.readonly`	getProfile, listMessages, getMessage, listThreads, getThread, listDrafts, listLabels
`gmail.compose`	createDraft, sendDraft, sendMessage
`gmail.modify`	modifyMessageLabels (mark read, archive, add/remove labels)

Common errors

401 Unauthorized: the access token expired or was revoked. Reconnect the credential (request offline_access / a refresh token).
403 Forbidden (insufficientPermissions): a scope is missing. Add it to the consent screen and reconnect. accessNotConfigured means the Gmail API is not enabled in the project.
400 Bad Request: usually an invalid raw value. It must be base64url (not standard base64) of a full RFC 2822 message.
429 Too Many Requests / rateLimitExceeded: per-user quota hit. Back off exponentially and retry.

Store the connection as a VX Agents OAuth credential. Never paste tokens into chat.

Usage guide

Setup

Connect a Google OAuth credential with the scopes gmail.readonly, gmail.compose and gmail.modify. The agent acts as the account that signed in.
Always pass userId = me (pin it as a preset).

Triage and reply to email

getProfile to learn the mailbox address (useful for the From header).
listMessages or listThreads with q in Gmail search syntax, e.g. is:unread newer_than:2d, from:[email protected] subject:invoice, in:inbox -category:promotions. Results are ids only; page with pageToken.
getThread (or getMessage) with format=full to read the conversation; use format=metadata + metadataHeaders=Subject,From,Message-ID to skim cheaply.
Write the reply and call createDraft with message.raw and message.threadId. Show the draft to the user.
Only after the user confirms, sendDraft with the draft id. Use sendMessage only for a new email the user has explicitly approved.
modifyMessageLabels to tidy up: remove UNREAD to mark read, remove INBOX to archive, add STARRED or a label id from listLabels.

Building `raw`

Write a plain RFC 2822 message, then base64url-encode it (+→-, /→_, strip =):

From: [email protected]
To: [email protected]
Subject: Re: Invoice 1042
In-Reply-To: <original Message-ID>
References: <original Message-ID>
Content-Type: text/plain; charset="UTF-8"

Hi Alice, ...

For replies keep the same Subject (with Re:) and set threadId, or Gmail starts a new thread.

Good to know

Sending email cannot be undone: always confirm recipients, subject and body with the user before sendDraft / sendMessage.
Body text in getMessage is base64url inside payload.parts[].body.data; prefer the text/plain part.
System labels: INBOX, UNREAD, STARRED, IMPORTANT, SPAM, TRASH, SENT, DRAFT. Custom labels need their id (Label_123), not the name.
internalDate is epoch milliseconds. maxResults max is 500.
This spec has no delete/trash operations by design.

How to use this spec

Create a free VX Agents account (sandbox tools included).
Open the marketplace and connect “Gmail Inbox & Send” to an agent.
Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.