# Gmail — how to use (mcp.ai)

Read, search and send Gmail messages straight from your AI agent.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_gmail?ms=1781044140000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `gmail_list`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/gmail`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/gmail/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/gmail/add/label/to/email` — Adds and/or removes specified gmail labels for a message; ensure `message id` and all `label ids` are valid (use 'listlabels' for custom label ids).
  - body: { user_id?: string, message_id: string, add_label_ids?: string[], remove_label_ids?: string[] }
- `POST https://api.mcp.ai/api/gmail/create/email/draft` — Creates a gmail email draft, supporting to/cc/bcc, subject, plain/html body (ensure `is html=true` for html), attachments, and threading.
  - body: { cc?: string[], bcc?: string[], body: string, is_html?: boolean, subject: string, user_id?: string, thread_id?: string, attachment?: object, recipient_email: string, extra_recipients?: string[] }
- `POST https://api.mcp.ai/api/gmail/create/label` — Creates a new label with a unique name in the specified user's gmail account.
  - body: { user_id?: string, label_name: string, text_color?: string, background_color?: string, label_list_visibility?: string, message_list_visibility?: string }
- `POST https://api.mcp.ai/api/gmail/delete/draft` — Permanently deletes a specific gmail draft using its id; ensure the draft exists and the user has necessary permissions for the given `user id`.
  - body: { user_id?: string, draft_id: string }
- `POST https://api.mcp.ai/api/gmail/delete/message` — Permanently deletes a specific email message by its id from a gmail mailbox; for `user id`, use 'me' for the authenticated user or an email address to which the authenticated user has delegated access
  - body: { user_id?: string, message_id: string }
- `POST https://api.mcp.ai/api/gmail/fetch/emails` — Fetches a list of email messages from a gmail account, supporting filtering, pagination, and optional full content retrieval.
  - body: { query?: string, user_id?: string, verbose?: boolean, ids_only?: boolean, label_ids?: string[], page_token?: string, max_results?: integer, include_payload?: boolean, include_spam_trash?: boolean }
- `POST https://api.mcp.ai/api/gmail/fetch/message/by/message/id` — Fetches a specific email message by its id, provided the `message id` exists and is accessible to the authenticated `user id`.
  - body: { format?: string, user_id?: string, message_id: string }
- `POST https://api.mcp.ai/api/gmail/fetch/message/by/thread/id` — Retrieves messages from a gmail thread using its `thread id`, where the thread must be accessible by the specified `user id`.
  - body: { user_id?: string, thread_id: string, page_token?: string }
- `POST https://api.mcp.ai/api/gmail/get/attachment` — Retrieves a specific attachment by id from a message in a user's gmail mailbox, requiring valid message and attachment ids.
  - body: { user_id?: string, file_name: string, message_id: string, attachment_id: string }
- `POST https://api.mcp.ai/api/gmail/get/contacts` — Fetches contacts (connections) for the authenticated google account, allowing selection of specific data fields and pagination.
  - body: { page_token?: string, person_fields?: string, resource_name?: string, include_other_contacts?: boolean }
- `POST https://api.mcp.ai/api/gmail/get/people` — Retrieves either a specific person's details (using `resource name`) or lists 'other contacts' (if `other contacts` is true), with `person fields` specifying the data to return.
  - body: { page_size?: integer, page_token?: string, sync_token?: string, person_fields?: string, resource_name?: string, other_contacts?: boolean }
- `POST https://api.mcp.ai/api/gmail/get/profile` — Retrieves key gmail profile information (email address, message/thread totals, history id) for a user.
  - body: { user_id?: string }
- `POST https://api.mcp.ai/api/gmail/list/drafts` — Retrieves a paginated list of email drafts from a user's gmail account. use verbose=true to get full draft details including subject, body, sender, and timestamp.
  - body: { user_id?: string, verbose?: boolean, page_token?: string, max_results?: integer }
- `POST https://api.mcp.ai/api/gmail/list/labels` — Retrieves a list of all system and user-created labels for the specified gmail account.
  - body: { user_id?: string }
- `POST https://api.mcp.ai/api/gmail/list/threads` — Retrieves a list of email threads from a gmail account, identified by `user id` (email address or 'me'), supporting filtering and pagination.
  - body: { query?: string, user_id?: string, verbose?: boolean, page_token?: string, max_results?: integer }
- `POST https://api.mcp.ai/api/gmail/modify/thread/labels` — Adds or removes specified existing label ids from a gmail thread, affecting all its messages; ensure the thread id is valid.
  - body: { user_id?: string, thread_id: string, add_label_ids?: string[], remove_label_ids?: string[] }
- `POST https://api.mcp.ai/api/gmail/move/to/trash` — Moves an existing, non-deleted email message to the trash for the specified user.
  - body: { user_id?: string, message_id: string }
- `POST https://api.mcp.ai/api/gmail/patch/label` — Patches the specified label.
  - body: { id: string, name?: string, color?: object, userId: string, labelListVisibility?: string, messageListVisibility?: string }
- `POST https://api.mcp.ai/api/gmail/remove/label` — Permanently deletes a specific, existing user-created gmail label by its id for a user; cannot delete system labels.
  - body: { user_id?: string, label_id: string }
- `POST https://api.mcp.ai/api/gmail/reply/to/thread` — Sends a reply within a specific gmail thread using the original thread's subject, requiring a valid `thread id` and correctly formatted email addresses. supports attachments via the `attachment` param
  - body: { cc?: string[], bcc?: string[], is_html?: boolean, user_id?: string, thread_id: string, attachment?: object, message_body: string, recipient_email: string, extra_recipients?: string[] }
- `POST https://api.mcp.ai/api/gmail/search/people` — Searches contacts by matching the query against names, nicknames, emails, phone numbers, and organizations, optionally including 'other contacts'.
  - body: { query: string, pageSize?: integer, person_fields?: string, other_contacts?: boolean }
- `POST https://api.mcp.ai/api/gmail/send/draft` — Sends the specified, existing draft to the recipients in the to, cc, and bcc headers.
  - body: { user_id?: string, draft_id: string }
- `POST https://api.mcp.ai/api/gmail/send/email` — Sends an email via gmail api using the authenticated user's google profile display name, requiring `is html=true` if the body contains html and valid `s3key`, `mimetype`, `name` for any attachment.
  - body: { cc?: string[], bcc?: string[], body: string, is_html?: boolean, subject?: string, user_id?: string, attachment?: object, recipient_email: string, extra_recipients?: string[] }

## More
- Page: https://mcp.ai/gmail
- Agent spec (llms.txt): https://mcp.ai/gmail/llms.txt
- Postman collection: https://mcp.ai/gmail/postman.json