Google

Gmail API (all endpoints)

The Gmail API lets you view and manage Gmail mailbox data like threads, messages, and labels.

Communication#openapi#analytics#media

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The Gmail API lets you view and manage Gmail mailbox data like threads, messages, and labels.

Endpoints 79

users

  • GETGets the current user's Gmail profile./gmail/v1/users/:userId/profileGets the current user's Gmail profile.
  • POSTTurn off push notification delivery for the given user mailbox/gmail/v1/users/:userId/stopTurn off push notification delivery for the given user mailbox. For more information, see Configure push notifications in Gmail API.
  • POSTSet up or update a push notification watch on the given user mailbox/gmail/v1/users/:userId/watchSet up or update a push notification watch on the given user mailbox. For more information, see Configure push notifications in Gmail API.

users.drafts

  • GETLists the drafts in the user's mailbox/gmail/v1/users/:userId/drafts?includeSpamTrash=true&maxResults=0&pageToken=string&q=stringLists the drafts in the user's mailbox. For more information, see Create and send draft emails.
  • POSTCreates a draft with the `DRAFT` label/gmail/v1/users/:userId/draftsCreates a draft with the DRAFT label. For more information, see Create and send draft emails.
  • GETGets the specified draft/gmail/v1/users/:userId/drafts/:id?format=minimalGets the specified draft. For more information, see Create and send draft emails.
  • PUTReplaces a draft's content/gmail/v1/users/:userId/drafts/:idReplaces a draft's content. For more information, see Create and send draft emails.
  • DELETEImmediately and permanently deletes the specified draft/gmail/v1/users/:userId/drafts/:idImmediately and permanently deletes the specified draft. Does not simply trash it. For more information, see Create and send draft emails.
  • POSTSends the specified, existing draft to the recipients in the `To`, `Cc`, and `Bcc` headers/gmail/v1/users/:userId/drafts/sendSends the specified, existing draft to the recipients in the To, Cc, and Bcc headers. For more information, see Create and send draft emails.

users.history

  • GETLists the history of all changes to the given mailbox/gmail/v1/users/:userId/history?historyTypes=messageAdded&labelId=string&maxResults=0&pageToken=string&startHistoryId=stringLists the history of all changes to the given mailbox. History results are returned in chronological order (increasing historyId). For more information, see…

users.labels

  • GETLists all labels in the user's mailbox/gmail/v1/users/:userId/labelsLists all labels in the user's mailbox. For more information, see Manage labels.
  • POSTCreates a label/gmail/v1/users/:userId/labelsCreates a label. For more information, see Manage labels.
  • GETGets the specified label/gmail/v1/users/:userId/labels/:idGets the specified label. For more information, see Manage labels.
  • PUTUpdates the specified label/gmail/v1/users/:userId/labels/:idUpdates the specified label. For more information, see Manage labels.
  • DELETEImmediately and permanently deletes the specified label and removes it from any messages and threads that it's applied…/gmail/v1/users/:userId/labels/:idImmediately and permanently deletes the specified label and removes it from any messages and threads that it's applied to. For more information, see Manage…
  • PATCHPatch the specified label/gmail/v1/users/:userId/labels/:idPatch the specified label. For more information, see Manage labels.

users.messages

  • POSTDeletes many messages by message ID/gmail/v1/users/:userId/messages/batchDeleteDeletes many messages by message ID. Provides no guarantees that messages were not already deleted or even existed at all.
  • POSTModifies the labels and the Classification Label values on the specified messages/gmail/v1/users/:userId/messages/batchModifyModifies the labels and the Classification Label values on the specified messages. For administrators modifying messages for users in their organization,…
  • GETGets the specified message./gmail/v1/users/:userId/messages/:id?format=minimal&metadataHeaders=stringGets the specified message.
  • DELETEImmediately and permanently deletes the specified message/gmail/v1/users/:userId/messages/:idImmediately and permanently deletes the specified message. This operation cannot be undone. Prefer messages.trash instead.
  • POSTImports a message into only this user's mailbox, with standard email delivery scanning and classification similar to…/gmail/v1/users/:userId/messages/import?deleted=true&internalDateSource=receivedTime&neverMarkSpam=true&processForCalendar=trueImports a message into only this user's mailbox, with standard email delivery scanning and classification similar to receiving via SMTP. This method doesn't…
  • GETLists the messages in the user's mailbox/gmail/v1/users/:userId/messages?includeSpamTrash=true&labelIds=string&maxResults=0&pageToken=string&q=stringLists the messages in the user's mailbox. For more information, see List Gmail messages.
  • POSTDirectly inserts a message into only this user's mailbox similar to `IMAP APPEND`, bypassing most scanning and…/gmail/v1/users/:userId/messages?deleted=true&internalDateSource=receivedTimeDirectly inserts a message into only this user's mailbox similar to IMAP APPEND, bypassing most scanning and classification. Does not send a message. For more…
  • POSTModifies the labels and the Classification Label values on the specified message/gmail/v1/users/:userId/messages/:id/modifyModifies the labels and the Classification Label values on the specified message. For administrators modifying message for users in their organization,…
  • POSTSends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers/gmail/v1/users/:userId/messages/sendSends the specified message to the recipients in the To, Cc, and Bcc headers. For more information, see Create and send email messages.
  • POSTMoves the specified message to the trash./gmail/v1/users/:userId/messages/:id/trashMoves the specified message to the trash.
  • POSTRemoves the specified message from the trash./gmail/v1/users/:userId/messages/:id/untrashRemoves the specified message from the trash.

users.messages.attachments

  • GETGets the specified message attachment./gmail/v1/users/:userId/messages/:messageId/attachments/:idGets the specified message attachment.

users.settings

  • GETGets the auto-forwarding setting for the specified account/gmail/v1/users/:userId/settings/autoForwardingGets the auto-forwarding setting for the specified account. For more information, see Manage email forwarding.
  • PUTUpdates the auto-forwarding setting for the specified account/gmail/v1/users/:userId/settings/autoForwardingUpdates the auto-forwarding setting for the specified account. A verified forwarding address must be specified when auto-forwarding is enabled. For more…
  • GETGets IMAP settings/gmail/v1/users/:userId/settings/imapGets IMAP settings. For more information, see Configure POP and IMAP settings with the Gmail API.
  • PUTUpdates IMAP settings/gmail/v1/users/:userId/settings/imapUpdates IMAP settings. For more information, see Configure POP and IMAP settings with the Gmail API.
  • GETGets language settings/gmail/v1/users/:userId/settings/languageGets language settings. For more information, see Manage language settings.
  • PUTUpdates language settings/gmail/v1/users/:userId/settings/languageUpdates language settings. For more information, see Manage language settings. If successful, the return object contains the displayLanguage that was saved…
  • GETGets POP settings/gmail/v1/users/:userId/settings/popGets POP settings. For more information, see Configure POP and IMAP settings with the Gmail API.
  • PUTUpdates POP settings/gmail/v1/users/:userId/settings/popUpdates POP settings. For more information, see Configure POP and IMAP settings with the Gmail API.
  • GETGets vacation responder settings/gmail/v1/users/:userId/settings/vacationGets vacation responder settings. For more information, see Manage vacation settings with the Gmail API.
  • PUTUpdates vacation responder settings/gmail/v1/users/:userId/settings/vacationUpdates vacation responder settings. For more information, see Manage vacation settings with the Gmail API.

users.settings.cse.identities

  • GETLists the client-side encrypted identities for an authenticated user/gmail/v1/users/:userId/settings/cse/identities?pageSize=0&pageToken=stringLists the client-side encrypted identities for an authenticated user. For administrators managing identities and keypairs for users in their organization,…
  • POSTCreates and configures a client-side encryption identity that's authorized to send mail from the user account/gmail/v1/users/:userId/settings/cse/identitiesCreates and configures a client-side encryption identity that's authorized to send mail from the user account. Google publishes the S/MIME certificate to a…
  • GETRetrieves a client-side encryption identity configuration/gmail/v1/users/:userId/settings/cse/identities/:cseEmailAddressRetrieves a client-side encryption identity configuration. For administrators managing identities and keypairs for users in their organization, requests…
  • DELETEDeletes a client-side encryption identity/gmail/v1/users/:userId/settings/cse/identities/:cseEmailAddressDeletes a client-side encryption identity. The authenticated user can no longer use the identity to send encrypted messages. You cannot restore the identity…
  • PATCHAssociates a different key pair with an existing client-side encryption identity/gmail/v1/users/:userId/settings/cse/identities/:emailAddressAssociates a different key pair with an existing client-side encryption identity. The updated key pair must validate against Google's S/MIME certificate…

users.settings.cse.keypairs

  • GETLists client-side encryption key pairs for an authenticated user/gmail/v1/users/:userId/settings/cse/keypairs?pageSize=0&pageToken=stringLists client-side encryption key pairs for an authenticated user. For administrators managing identities and keypairs for users in their organization,…
  • POSTCreates and uploads a client-side encryption S/MIME public key certificate chain and private key metadata for the…/gmail/v1/users/:userId/settings/cse/keypairs?chainValidation=allCreates and uploads a client-side encryption S/MIME public key certificate chain and private key metadata for the authenticated user. For administrators…
  • POSTTurns off a client-side encryption key pair/gmail/v1/users/:userId/settings/cse/keypairs/:keyPairId:disableTurns off a client-side encryption key pair. The authenticated user can no longer use the key pair to decrypt incoming CSE message texts or sign outgoing CSE…
  • POSTTurns on a client-side encryption key pair that was turned off/gmail/v1/users/:userId/settings/cse/keypairs/:keyPairId:enableTurns on a client-side encryption key pair that was turned off. The key pair becomes active again for any associated client-side encryption identities. For…
  • GETRetrieves an existing client-side encryption key pair/gmail/v1/users/:userId/settings/cse/keypairs/:keyPairIdRetrieves an existing client-side encryption key pair. For administrators managing identities and keypairs for users in their organization, requests require…
  • POSTDeletes a client-side encryption key pair permanently and immediately/gmail/v1/users/:userId/settings/cse/keypairs/:keyPairId:obliterateDeletes a client-side encryption key pair permanently and immediately. You can only permanently delete key pairs that have been turned off for more than 30…

users.settings.delegates

  • GETLists the delegates for the specified account/gmail/v1/users/:userId/settings/delegatesLists the delegates for the specified account. For more information, see Manage delegates. This method is only available to service account clients that have…
  • POSTAdds a delegate with its verification status set directly to `accepted`, without sending any verification email/gmail/v1/users/:userId/settings/delegatesAdds a delegate with its verification status set directly to accepted, without sending any verification email. The delegate user must be a member of the same…
  • GETGets the specified delegate/gmail/v1/users/:userId/settings/delegates/:delegateEmailGets the specified delegate. For more information, see Manage delegates. A delegate user must be referred to by their primary email address, and not an email…
  • DELETERemoves the specified delegate (which can be of any verification status), and revokes any verification that may have…/gmail/v1/users/:userId/settings/delegates/:delegateEmailRemoves the specified delegate (which can be of any verification status), and revokes any verification that may have been required for using it. For more…

users.settings.filters

  • GETLists the message filters of a Gmail user/gmail/v1/users/:userId/settings/filtersLists the message filters of a Gmail user. For more information, see Manage Gmail filters.
  • POSTCreates a filter/gmail/v1/users/:userId/settings/filtersCreates a filter. Note: you can only create a maximum of 1,000 filters. For more information, see Manage Gmail filters.
  • GETGets a filter/gmail/v1/users/:userId/settings/filters/:idGets a filter. For more information, see Manage Gmail filters.
  • DELETEImmediately and permanently deletes the specified filter/gmail/v1/users/:userId/settings/filters/:idImmediately and permanently deletes the specified filter. For more information, see Manage Gmail filters.

users.settings.forwardingAddresses

  • GETLists the forwarding addresses for the specified account/gmail/v1/users/:userId/settings/forwardingAddressesLists the forwarding addresses for the specified account. For more information, see Manage email forwarding.
  • POSTCreates a forwarding address/gmail/v1/users/:userId/settings/forwardingAddressesCreates a forwarding address. If ownership verification is required, a message will be sent to the recipient and the resource's verification status will be…
  • GETGets the specified forwarding address/gmail/v1/users/:userId/settings/forwardingAddresses/:forwardingEmailGets the specified forwarding address. For more information, see Manage email forwarding.
  • DELETEDeletes the specified forwarding address and revokes any verification that may have been required/gmail/v1/users/:userId/settings/forwardingAddresses/:forwardingEmailDeletes the specified forwarding address and revokes any verification that may have been required. For more information, see Manage email forwarding. This…

users.settings.sendAs

  • GETLists the send-as aliases for the specified account/gmail/v1/users/:userId/settings/sendAsLists the send-as aliases for the specified account. The result includes the primary send-as address associated with the account as well as any custom "from"…
  • POSTCreates a custom "from" send-as alias/gmail/v1/users/:userId/settings/sendAsCreates a custom "from" send-as alias. If an SMTP MSA is specified, Gmail will attempt to connect to the SMTP service to validate the configuration before…
  • GETGets the specified send-as alias/gmail/v1/users/:userId/settings/sendAs/:sendAsEmailGets the specified send-as alias. Fails with an HTTP 404 error if the specified address is not a member of the collection. For more information, see Manage…
  • PUTUpdates a send-as alias/gmail/v1/users/:userId/settings/sendAs/:sendAsEmailUpdates a send-as alias. If a signature is provided, Gmail will sanitize the HTML before saving it with the alias. For more information, see Manage aliases…
  • DELETEDeletes the specified send-as alias/gmail/v1/users/:userId/settings/sendAs/:sendAsEmailDeletes the specified send-as alias. Revokes any verification that may have been required for using it. For more information, see Manage aliases and…
  • PATCHPatch the specified send-as alias/gmail/v1/users/:userId/settings/sendAs/:sendAsEmailPatch the specified send-as alias. For more information, see Manage aliases and signatures with the Gmail API.
  • POSTSends a verification email to the specified send-as alias address/gmail/v1/users/:userId/settings/sendAs/:sendAsEmail/verifySends a verification email to the specified send-as alias address. The verification status must be pending. For more information, see Manage aliases and…

users.settings.sendAs.smimeInfo

  • GETGets the specified S/MIME config for the specified send-as alias/gmail/v1/users/:userId/settings/sendAs/:sendAsEmail/smimeInfo/:idGets the specified S/MIME config for the specified send-as alias. For more information, see Manage S/MIME certificates with the Gmail API.
  • DELETEDeletes the specified S/MIME config for the specified send-as alias/gmail/v1/users/:userId/settings/sendAs/:sendAsEmail/smimeInfo/:idDeletes the specified S/MIME config for the specified send-as alias. For more information, see Manage S/MIME certificates with the Gmail API.
  • GETLists S/MIME configs for the specified send-as alias/gmail/v1/users/:userId/settings/sendAs/:sendAsEmail/smimeInfoLists S/MIME configs for the specified send-as alias. For more information, see Manage S/MIME certificates with the Gmail API.
  • POSTInsert (upload) the given S/MIME config for the specified send-as alias/gmail/v1/users/:userId/settings/sendAs/:sendAsEmail/smimeInfoInsert (upload) the given S/MIME config for the specified send-as alias. Note that pkcs12 format is required for the key. For more information, see Manage…
  • POSTSets the default S/MIME config for the specified send-as alias/gmail/v1/users/:userId/settings/sendAs/:sendAsEmail/smimeInfo/:id/setDefaultSets the default S/MIME config for the specified send-as alias. For more information, see Manage S/MIME certificates with the Gmail API.

users.threads

  • GETGets the specified thread/gmail/v1/users/:userId/threads/:id?format=full&metadataHeaders=stringGets the specified thread. For more information, see Manage threads.
  • DELETEImmediately and permanently deletes the specified thread/gmail/v1/users/:userId/threads/:idImmediately and permanently deletes the specified thread. Any messages that belong to the thread are also deleted. This operation cannot be undone. Prefer…
  • GETLists the threads in the user's mailbox/gmail/v1/users/:userId/threads?includeSpamTrash=true&labelIds=string&maxResults=0&pageToken=string&q=stringLists the threads in the user's mailbox. For more information, see Manage threads.
  • POSTModifies the labels applied to the thread/gmail/v1/users/:userId/threads/:id/modifyModifies the labels applied to the thread. This applies to all messages in the thread. For more information, see Manage threads.
  • POSTMoves the specified thread to the trash/gmail/v1/users/:userId/threads/:id/trashMoves the specified thread to the trash. Any messages that belong to the thread are also moved to the trash. For more information, see Manage threads.
  • POSTRemoves the specified thread from the trash/gmail/v1/users/:userId/threads/:id/untrashRemoves the specified thread from the trash. Any messages that belong to the thread are also removed from the trash. For more information, see Manage threads.

API details

Base URL
https://gmail.googleapis.com
Authentication
OAuth 2.0 (authorization code flow) with 26 scopes
An API key in the key query parameter
Operations
79 operations on 49 pathsGET 30POST 28DELETE 10PUT 8PATCH 3
Main resources
users.messages 11users.settings 10users.settings.sendAs 7users.drafts 6users.labels 6users.settings.cse.keypairs 6users.threads 6users.settings.cse.identities 5users.settings.sendAs.smimeInfo 5users.settings.delegates 4
Response formats
application/json
Description format
Google API Discovery, API version v1

How to test the Gmail API (all endpoints) in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Gmail API (all endpoints) collection, without the publisher's secrets.
  3. Add your credentialsThis API uses OAuth 2.0 (authorization code flow) with 26 scopes. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Gets the current user's Gmail profile.” (GET /gmail/v1/users/:userId/profile), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Gmail API (all endpoints)?

The Gmail API lets you view and manage Gmail mailbox data like threads, messages, and labels. It is listed under Communication and has 79 endpoints.

Who publishes the Gmail API (all endpoints)?

It is listed from Google's public API description (an OpenAPI document), not published by Google on Swastik Codes. Anyone who controls googleapis.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Gmail API (all endpoints)?

Requests go to https://gmail.googleapis.com. Endpoint paths are added to this base URL.

How do I authenticate with the Gmail API (all endpoints)?

It accepts 2 methods: OAuth 2.0 (authorization code flow) with 26 scopes; an API key in the key query parameter.

How many endpoints does the Gmail API (all endpoints) have?

79 operations on 49 paths (30 GET, 28 POST, 10 DELETE, 8 PUT, 3 PATCH). The largest groups are users.messages, users.settings, users.settings.sendAs, users.drafts.

Is forking the Gmail API (all endpoints) free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.