The Gmail API from Google Gmail — 19 operation(s) for gmail.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/google-gmail-gmail-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Google Gmail API
description: The Gmail API lets you view and manage Gmail mailbox data like threads, messages, and labels. It provides RESTful access to Gmail mailboxes including message sending, drafting, organizing with labels, managing settings, and push notifications for mailbox changes.
version: v1
contact:
name: Google
url: https://developers.google.com/workspace/gmail/api/guides
servers:
- url: https://gmail.googleapis.com
tags:
- name: Gmail
paths:
/gmail/v1/users/{userId}/profile:
get:
operationId: getUserProfile
summary: Google Gmail Get user profile
description: Gets the current user's Gmail profile.
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
tags:
- Gmail
/gmail/v1/users/{userId}/messages:
get:
operationId: listMessages
summary: Google Gmail List messages
description: Lists the messages in the user's mailbox.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: maxResults
in: query
schema:
type: integer
- name: pageToken
in: query
schema:
type: string
- name: q
in: query
schema:
type: string
- name: labelIds
in: query
schema:
type: array
items:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListMessagesResponse'
tags:
- Gmail
post:
operationId: insertMessage
summary: Google Gmail Insert message
description: Directly inserts a message into the user's mailbox.
parameters:
- name: userId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
tags:
- Gmail
/gmail/v1/users/{userId}/messages/{id}:
get:
operationId: getMessage
summary: Google Gmail Get message
description: Gets the specified message.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
- name: format
in: query
schema:
type: string
enum:
- minimal
- full
- raw
- metadata
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
tags:
- Gmail
delete:
operationId: deleteMessage
summary: Google Gmail Delete message
description: Immediately and permanently deletes the specified message.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: Successful deletion
tags:
- Gmail
/gmail/v1/users/{userId}/messages/send:
post:
operationId: sendMessage
summary: Google Gmail Send message
description: Sends the specified message to the recipients.
parameters:
- name: userId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
tags:
- Gmail
/gmail/v1/users/{userId}/messages/{id}/modify:
post:
operationId: modifyMessage
summary: Google Gmail Modify message
description: Modifies the labels on the specified message.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyMessageRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
tags:
- Gmail
/gmail/v1/users/{userId}/messages/{id}/trash:
post:
operationId: trashMessage
summary: Google Gmail Trash message
description: Moves the specified message to the trash.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
tags:
- Gmail
/gmail/v1/users/{userId}/messages/{id}/untrash:
post:
operationId: untrashMessage
summary: Google Gmail Untrash message
description: Removes the specified message from the trash.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
tags:
- Gmail
/gmail/v1/users/{userId}/labels:
get:
operationId: listLabels
summary: Google Gmail List labels
description: Lists all labels in the user's mailbox.
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListLabelsResponse'
tags:
- Gmail
post:
operationId: createLabel
summary: Google Gmail Create label
description: Creates a new label.
parameters:
- name: userId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Label'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Label'
tags:
- Gmail
/gmail/v1/users/{userId}/labels/{id}:
get:
operationId: getLabel
summary: Google Gmail Get label
description: Gets the specified label.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Label'
tags:
- Gmail
put:
operationId: updateLabel
summary: Google Gmail Update label
description: Updates the specified label.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Label'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Label'
tags:
- Gmail
delete:
operationId: deleteLabel
summary: Google Gmail Delete label
description: Immediately and permanently deletes the specified label.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: Successful deletion
tags:
- Gmail
/gmail/v1/users/{userId}/threads:
get:
operationId: listThreads
summary: Google Gmail List threads
description: Lists the threads in the user's mailbox.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: maxResults
in: query
schema:
type: integer
- name: pageToken
in: query
schema:
type: string
- name: q
in: query
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListThreadsResponse'
tags:
- Gmail
/gmail/v1/users/{userId}/threads/{id}:
get:
operationId: getThread
summary: Google Gmail Get thread
description: Gets the specified thread.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Thread'
tags:
- Gmail
delete:
operationId: deleteThread
summary: Google Gmail Delete thread
description: Immediately and permanently deletes the specified thread.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: Successful deletion
tags:
- Gmail
/gmail/v1/users/{userId}/drafts:
get:
operationId: listDrafts
summary: Google Gmail List drafts
description: Lists the drafts in the user's mailbox.
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListDraftsResponse'
tags:
- Gmail
post:
operationId: createDraft
summary: Google Gmail Create draft
description: Creates a new draft with the DRAFT label.
parameters:
- name: userId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Draft'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Draft'
tags:
- Gmail
/gmail/v1/users/{userId}/drafts/{id}:
get:
operationId: getDraft
summary: Google Gmail Get draft
description: Gets the specified draft.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Draft'
tags:
- Gmail
put:
operationId: updateDraft
summary: Google Gmail Update draft
description: Replaces a draft's content.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Draft'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Draft'
tags:
- Gmail
delete:
operationId: deleteDraft
summary: Google Gmail Delete draft
description: Immediately and permanently deletes the specified draft.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: Successful deletion
tags:
- Gmail
/gmail/v1/users/{userId}/drafts/send:
post:
operationId: sendDraft
summary: Google Gmail Send draft
description: Sends the specified existing draft to the recipients.
parameters:
- name: userId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Draft'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
tags:
- Gmail
/gmail/v1/users/{userId}/history:
get:
operationId: listHistory
summary: Google Gmail List history
description: Lists the history of all changes to the given mailbox.
parameters:
- name: userId
in: path
required: true
schema:
type: string
- name: startHistoryId
in: query
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListHistoryResponse'
tags:
- Gmail
/gmail/v1/users/{userId}/watch:
post:
operationId: watchMailbox
summary: Google Gmail Watch mailbox
description: Set up or update a push notification watch on the given user mailbox.
parameters:
- name: userId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WatchRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/WatchResponse'
tags:
- Gmail
/gmail/v1/users/{userId}/stop:
post:
operationId: stopMailboxWatch
summary: Google Gmail Stop watching mailbox
description: Stop receiving push notifications for the given user mailbox.
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'204':
description: Successful response
tags:
- Gmail
/gmail/v1/users/{userId}/settings/autoForwarding:
get:
operationId: getAutoForwarding
summary: Google Gmail Get auto-forwarding settings
description: Gets the auto-forwarding setting for the specified account.
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
tags:
- Gmail
/gmail/v1/users/{userId}/settings/filters:
get:
operationId: listFilters
summary: Google Gmail List filters
description: Lists the message filters of a Gmail user.
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
tags:
- Gmail
post:
operationId: createFilter
summary: Google Gmail Create filter
description: Creates a filter.
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
tags:
- Gmail
components:
schemas:
Thread:
type: object
properties:
id:
type: string
snippet:
type: string
historyId:
type: string
messages:
type: array
items:
$ref: '#/components/schemas/Message'
WatchResponse:
type: object
properties:
historyId:
type: string
expiration:
type: string
ModifyMessageRequest:
type: object
properties:
addLabelIds:
type: array
items:
type: string
removeLabelIds:
type: array
items:
type: string
Profile:
type: object
properties:
emailAddress:
type: string
messagesTotal:
type: integer
threadsTotal:
type: integer
historyId:
type: string
ListDraftsResponse:
type: object
properties:
drafts:
type: array
items:
$ref: '#/components/schemas/Draft'
nextPageToken:
type: string
resultSizeEstimate:
type: integer
ListMessagesResponse:
type: object
properties:
messages:
type: array
items:
$ref: '#/components/schemas/Message'
nextPageToken:
type: string
resultSizeEstimate:
type: integer
ListHistoryResponse:
type: object
properties:
history:
type: array
items:
type: object
nextPageToken:
type: string
historyId:
type: string
WatchRequest:
type: object
properties:
labelIds:
type: array
items:
type: string
labelFilterAction:
type: string
enum:
- include
- exclude
topicName:
type: string
Label:
type: object
properties:
id:
type: string
name:
type: string
messageListVisibility:
type: string
labelListVisibility:
type: string
type:
type: string
enum:
- system
- user
ListLabelsResponse:
type: object
properties:
labels:
type: array
items:
$ref: '#/components/schemas/Label'
Draft:
type: object
properties:
id:
type: string
message:
$ref: '#/components/schemas/Message'
ListThreadsResponse:
type: object
properties:
threads:
type: array
items:
$ref: '#/components/schemas/Thread'
nextPageToken:
type: string
resultSizeEstimate:
type: integer
Message:
type: object
properties:
id:
type: string
threadId:
type: string
labelIds:
type: array
items:
type: string
snippet:
type: string
historyId:
type: string
internalDate:
type: string
sizeEstimate:
type: integer
raw:
type: string