Google Workspace (G Suite)

Google Workspace (G Suite) Gmail API

The Gmail API from Google Workspace (G Suite) — 10 operation(s) for gmail.

GitHub OpenAPI

Operations 11

GET /gmail/v1/users/{userId}/profile Get user profile #
POST /gmail/v1/users/{userId}/watch Watch for changes #
POST /gmail/v1/users/{userId}/stop Stop push notifications #
GET /gmail/v1/users/{userId}/drafts List drafts #
POST /gmail/v1/users/{userId}/drafts Create draft #
POST /gmail/v1/users/{userId}/drafts/send Send draft #
GET /gmail/v1/users/{userId}/messages List messages #
POST /gmail/v1/users/{userId}/messages/send Send message #
GET /gmail/v1/users/{userId}/labels List labels #
GET /gmail/v1/users/{userId}/threads List threads #
PUT /gmail/v1/users/{userId}/settings/vacation Update vacation settings #

Documentation

📖
Documentation
https://developers.google.com/gmail/api/guides
📖
Authentication
https://developers.google.com/gmail/api/auth/about-auth
📖
Documentation
https://developers.google.com/calendar/api/guides/overview
📖
Authentication
https://developers.google.com/calendar/api/guides/auth
📖
GettingStarted
https://developers.google.com/calendar/api/quickstart/python
📖
Documentation
https://developers.google.com/drive/api/guides/about-sdk
📖
Authentication
https://developers.google.com/drive/api/guides/about-auth
📖
Documentation
https://developers.google.com/docs/api/how-tos/overview
📖
GettingStarted
https://developers.google.com/docs/api/quickstart/python
📖
Documentation
https://developers.google.com/sheets/api/guides/concepts
📖
Authentication
https://developers.google.com/sheets/api/guides/authorizing
📖
Documentation
https://developers.google.com/slides/how-tos/overview
📖
Documentation
https://developers.google.com/chat/api/guides/overview
📖
Documentation
https://developers.google.com/admin-sdk/directory/v1/guides

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/google-suite/refs/heads/main/openapi/google-suite-gmail-api-openapi.yml

Other Resources

🔗
Pricing
https://developers.google.com/gmail/api/reference/quota
🔗
Pricing
https://developers.google.com/drive/api/guides/limits
🔗
Examples
https://developers.google.com/sheets/api/samples
🔗
Examples
https://developers.google.com/slides/samples
🔗
Concepts
https://developers.google.com/chat/api/guides/concepts
🔗
Directory API
https://developers.google.com/admin-sdk/directory
🔗
Reports API
https://developers.google.com/admin-sdk/reports

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/google-suite-gmail-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

google-suite-gmail-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Gmail API
  description: 'The Gmail API lets you view and manage Gmail mailbox data including

    threads, messages, drafts, labels, settings, and watch/push notifications.

    This OpenAPI describes the Gmail surface of the Google Workspace (G Suite)

    API family.

    '
  version: v1
servers:
- url: https://gmail.googleapis.com
security:
- OAuth2:
  - gmail.readonly
- OAuth2:
  - gmail.modify
- OAuth2:
  - gmail.send
- OAuth2:
  - gmail.labels
tags:
- name: Gmail
paths:
  /gmail/v1/users/{userId}/profile:
    get:
      summary: Get user profile
      operationId: getProfile
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
        example: me
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  emailAddress:
                    type: string
                  messagesTotal:
                    type: integer
                  threadsTotal:
                    type: integer
                  historyId:
                    type: string
      tags:
      - Gmail
  /gmail/v1/users/{userId}/watch:
    post:
      summary: Watch for changes
      description: Enable push notifications for mailbox changes via Cloud Pub/Sub.
      operationId: watch
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                labelIds:
                  type: array
                  items:
                    type: string
                labelFilterAction:
                  type: string
                  enum:
                  - include
                  - exclude
                topicName:
                  type: string
      responses:
        '200':
          description: Watch response
          content:
            application/json:
              schema:
                type: object
                properties:
                  historyId:
                    type: string
                  expiration:
                    type: string
      tags:
      - Gmail
  /gmail/v1/users/{userId}/stop:
    post:
      summary: Stop push notifications
      operationId: stop
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Empty
      tags:
      - Gmail
  /gmail/v1/users/{userId}/drafts:
    get:
      summary: List drafts
      operationId: listDrafts
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: q
        in: query
        schema:
          type: string
      - name: maxResults
        in: query
        schema:
          type: integer
      - name: pageToken
        in: query
        schema:
          type: string
      - name: includeSpamTrash
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Draft list
          content:
            application/json:
              schema:
                type: object
                properties:
                  drafts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Draft'
                  nextPageToken:
                    type: string
                  resultSizeEstimate:
                    type: integer
      tags:
      - Gmail
    post:
      summary: Create draft
      operationId: createDraft
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Draft'
      responses:
        '200':
          description: Created draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draft'
      tags:
      - Gmail
  /gmail/v1/users/{userId}/drafts/send:
    post:
      summary: Send draft
      operationId: sendDraft
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Draft'
      responses:
        '200':
          description: Sent message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
      tags:
      - Gmail
  /gmail/v1/users/{userId}/messages:
    get:
      summary: List messages
      operationId: listMessages
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: q
        in: query
        schema:
          type: string
      - name: labelIds
        in: query
        schema:
          type: array
          items:
            type: string
      - name: maxResults
        in: query
        schema:
          type: integer
      - name: pageToken
        in: query
        schema:
          type: string
      - name: includeSpamTrash
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Message list
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
                  nextPageToken:
                    type: string
                  resultSizeEstimate:
                    type: integer
      tags:
      - Gmail
  /gmail/v1/users/{userId}/messages/send:
    post:
      summary: Send message
      operationId: sendMessage
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
      responses:
        '200':
          description: Sent message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
      tags:
      - Gmail
  /gmail/v1/users/{userId}/labels:
    get:
      summary: List labels
      operationId: listLabels
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Label list
          content:
            application/json:
              schema:
                type: object
                properties:
                  labels:
                    type: array
                    items:
                      $ref: '#/components/schemas/Label'
      tags:
      - Gmail
  /gmail/v1/users/{userId}/threads:
    get:
      summary: List threads
      operationId: listThreads
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: q
        in: query
        schema:
          type: string
      - name: labelIds
        in: query
        schema:
          type: array
          items:
            type: string
      - name: maxResults
        in: query
        schema:
          type: integer
      - name: pageToken
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Thread list
          content:
            application/json:
              schema:
                type: object
                properties:
                  threads:
                    type: array
                    items:
                      type: object
                  nextPageToken:
                    type: string
      tags:
      - Gmail
  /gmail/v1/users/{userId}/settings/vacation:
    put:
      summary: Update vacation settings
      operationId: updateVacationSettings
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enableAutoReply:
                  type: boolean
                responseSubject:
                  type: string
                responseBodyPlainText:
                  type: string
                responseBodyHtml:
                  type: string
                restrictToContacts:
                  type: boolean
                restrictToDomain:
                  type: boolean
                startTime:
                  type: string
                endTime:
                  type: string
      responses:
        '200':
          description: Updated vacation settings
          content:
            application/json:
              schema:
                type: object
      tags:
      - Gmail
components:
  schemas:
    Label:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        messageListVisibility:
          type: string
        labelListVisibility:
          type: string
        type:
          type: string
        messagesTotal:
          type: integer
        messagesUnread:
          type: integer
        threadsTotal:
          type: integer
        threadsUnread:
          type: integer
        color:
          type: object
          properties:
            textColor:
              type: string
            backgroundColor:
              type: string
    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
        payload:
          type: object
        sizeEstimate:
          type: integer
        raw:
          type: string
          format: byte
    Draft:
      type: object
      properties:
        id:
          type: string
        message:
          $ref: '#/components/schemas/Message'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            gmail.readonly: Read all resources and metadata
            gmail.modify: All read/write operations except immediate, permanent deletion
            gmail.send: Send messages only
            gmail.labels: Manage mailbox labels
            gmail.compose: Create, read, update, and delete drafts; send messages and drafts