openapi: 3.1.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 Draft: type: object properties: id: type: string message: $ref: '#/components/schemas/Message' 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 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