Skip to content
OpenParablePublic APIs

Gmail API API

by googleapis.com

OAuthHTTPSAnalytics
Open documentation ↗

Overview

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

Gmail API is an analytics API from googleapis.com. Requests are authenticated with OAuth. It is served over HTTPS. Its OpenAPI description documents 79 endpoints.

At a glance

Authentication
OAuth
HTTPS
Yes
CORS
Unknown
Category
Analytics
Base URL
https://gmail.googleapis.com/
Version
v1
Endpoints
79
OpenAPI
Specification ↗
Spec updated
2023-04-21

Make a first request

Replace the placeholders; the documentation says exactly where credentials go.

cURL
curl -X GET "https://gmail.googleapis.com/gmail/v1/users/USERID/drafts" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
JavaScript
const response = await fetch("https://gmail.googleapis.com/gmail/v1/users/USERID/drafts", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_TOKEN",
  },
});
const data = await response.json();
console.log(data);
Python
import requests

response = requests.request(
    "GET",
    "https://gmail.googleapis.com/gmail/v1/users/USERID/drafts",
    headers={
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_TOKEN",
    },
    timeout=30,
)
print(response.json())

Endpoints

MethodPathWhat it does
GET/gmail/v1/users/{userId}/draftsLists the drafts in the user's mailbox.
POST/gmail/v1/users/{userId}/draftsCreates a new draft with the `DRAFT` label.
POST/gmail/v1/users/{userId}/drafts/sendSends the specified, existing draft to the recipients in the `To`, `Cc`, and `Bcc` headers.
GET/gmail/v1/users/{userId}/drafts/{id}Gets the specified draft.
PUT/gmail/v1/users/{userId}/drafts/{id}Replaces a draft's content.
DELETE/gmail/v1/users/{userId}/drafts/{id}Immediately and permanently deletes the specified draft. Does not simply trash it.
GET/gmail/v1/users/{userId}/historyLists the history of all changes to the given mailbox. History results are returned in chronological order (increasing `historyId`).
GET/gmail/v1/users/{userId}/labelsLists all labels in the user's mailbox.
POST/gmail/v1/users/{userId}/labelsCreates a new label.
GET/gmail/v1/users/{userId}/labels/{id}Gets the specified label.
PUT/gmail/v1/users/{userId}/labels/{id}Updates the specified label.
PATCH/gmail/v1/users/{userId}/labels/{id}Patch the specified label.
DELETE/gmail/v1/users/{userId}/labels/{id}Immediately and permanently deletes the specified label and removes it from any messages and threads that it is applied to.
GET/gmail/v1/users/{userId}/messagesLists the messages in the user's mailbox.
POST/gmail/v1/users/{userId}/messagesDirectly inserts a message into only this user's mailbox similar to `IMAP APPEND`, bypassing most scanning and classification. Does not send a message.
POST/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.
POST/gmail/v1/users/{userId}/messages/batchModifyModifies the labels on the specified messages.
POST/gmail/v1/users/{userId}/messages/importImports a message into only this user's mailbox, with standard email delivery scanning and classification similar to receiving via SMTP. This method doesn't per
POST/gmail/v1/users/{userId}/messages/sendSends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers. For example usage, see [Sending email](https://developers.google.com/gmail/a
GET/gmail/v1/users/{userId}/messages/{id}Gets the specified message.
DELETE/gmail/v1/users/{userId}/messages/{id}Immediately and permanently deletes the specified message. This operation cannot be undone. Prefer `messages.trash` instead.
POST/gmail/v1/users/{userId}/messages/{id}/modifyModifies the labels on the specified message.
POST/gmail/v1/users/{userId}/messages/{id}/trashMoves the specified message to the trash.
POST/gmail/v1/users/{userId}/messages/{id}/untrashRemoves the specified message from the trash.
GET/gmail/v1/users/{userId}/messages/{messageId}/attachments/{id}Gets the specified message attachment.
GET/gmail/v1/users/{userId}/profileGets the current user's Gmail profile.
GET/gmail/v1/users/{userId}/settings/autoForwardingGets the auto-forwarding setting for the specified account.
PUT/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. This method is o
GET/gmail/v1/users/{userId}/settings/cse/identitiesLists the client-side encrypted identities for an authenticated user.
POST/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 shar
GET/gmail/v1/users/{userId}/settings/cse/identities/{cseEmailAddress}Retrieves a client-side encryption identity configuration.
DELETE/gmail/v1/users/{userId}/settings/cse/identities/{cseEmailAddress}Deletes a client-side encryption identity. The authenticated user can no longer use the identity to send encrypted messages. You cannot restore the identity aft
PATCH/gmail/v1/users/{userId}/settings/cse/identities/{emailAddress}Associates a different key pair with an existing client-side encryption identity. The updated key pair must validate against Google's [S/MIME certificate profil
GET/gmail/v1/users/{userId}/settings/cse/keypairsLists client-side encryption key pairs for an authenticated user.
POST/gmail/v1/users/{userId}/settings/cse/keypairsCreates and uploads a client-side encryption S/MIME public key certificate chain and private key metadata for the authenticated user.
GET/gmail/v1/users/{userId}/settings/cse/keypairs/{keyPairId}Retrieves an existing client-side encryption key pair.
POST/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 ma
POST/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.
POST/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 days
GET/gmail/v1/users/{userId}/settings/delegatesLists the delegates for the specified account. This method is only available to service account clients that have been delegated domain-wide authority.
POST/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
GET/gmail/v1/users/{userId}/settings/delegates/{delegateEmail}Gets the specified delegate. Note that a delegate user must be referred to by their primary email address, and not an email alias. This method is only available
DELETE/gmail/v1/users/{userId}/settings/delegates/{delegateEmail}Removes the specified delegate (which can be of any verification status), and revokes any verification that may have been required for using it. Note that a del
GET/gmail/v1/users/{userId}/settings/filtersLists the message filters of a Gmail user.
POST/gmail/v1/users/{userId}/settings/filtersCreates a filter. Note: you can only create a maximum of 1,000 filters.
GET/gmail/v1/users/{userId}/settings/filters/{id}Gets a filter.
DELETE/gmail/v1/users/{userId}/settings/filters/{id}Immediately and permanently deletes the specified filter.
GET/gmail/v1/users/{userId}/settings/forwardingAddressesLists the forwarding addresses for the specified account.
POST/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 set
GET/gmail/v1/users/{userId}/settings/forwardingAddresses/{forwardingEmail}Gets the specified forwarding address.
DELETE/gmail/v1/users/{userId}/settings/forwardingAddresses/{forwardingEmail}Deletes the specified forwarding address and revokes any verification that may have been required. This method is only available to service account clients that
GET/gmail/v1/users/{userId}/settings/imapGets IMAP settings.
PUT/gmail/v1/users/{userId}/settings/imapUpdates IMAP settings.
GET/gmail/v1/users/{userId}/settings/languageGets language settings.
PUT/gmail/v1/users/{userId}/settings/languageUpdates language settings. If successful, the return object contains the `displayLanguage` that was saved for the user, which may differ from the value passed i
GET/gmail/v1/users/{userId}/settings/popGets POP settings.
PUT/gmail/v1/users/{userId}/settings/popUpdates POP settings.
GET/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" al
POST/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 creat
GET/gmail/v1/users/{userId}/settings/sendAs/{sendAsEmail}Gets the specified send-as alias. Fails with an HTTP 404 error if the specified address is not a member of the collection.
PUT/gmail/v1/users/{userId}/settings/sendAs/{sendAsEmail}Updates a send-as alias. If a signature is provided, Gmail will sanitize the HTML before saving it with the alias. Addresses other than the primary address for
PATCH/gmail/v1/users/{userId}/settings/sendAs/{sendAsEmail}Patch the specified send-as alias.
DELETE/gmail/v1/users/{userId}/settings/sendAs/{sendAsEmail}Deletes the specified send-as alias. Revokes any verification that may have been required for using it. This method is only available to service account clients
GET/gmail/v1/users/{userId}/settings/sendAs/{sendAsEmail}/smimeInfoLists S/MIME configs for the specified send-as alias.
POST/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.
GET/gmail/v1/users/{userId}/settings/sendAs/{sendAsEmail}/smimeInfo/{id}Gets the specified S/MIME config for the specified send-as alias.
DELETE/gmail/v1/users/{userId}/settings/sendAs/{sendAsEmail}/smimeInfo/{id}Deletes the specified S/MIME config for the specified send-as alias.
POST/gmail/v1/users/{userId}/settings/sendAs/{sendAsEmail}/smimeInfo/{id}/setDefaultSets the default S/MIME config for the specified send-as alias.
POST/gmail/v1/users/{userId}/settings/sendAs/{sendAsEmail}/verifySends a verification email to the specified send-as alias address. The verification status must be `pending`. This method is only available to service account c
GET/gmail/v1/users/{userId}/settings/vacationGets vacation responder settings.
PUT/gmail/v1/users/{userId}/settings/vacationUpdates vacation responder settings.
POST/gmail/v1/users/{userId}/stopStop receiving push notifications for the given user mailbox.
GET/gmail/v1/users/{userId}/threadsLists the threads in the user's mailbox.
GET/gmail/v1/users/{userId}/threads/{id}Gets the specified thread.
DELETE/gmail/v1/users/{userId}/threads/{id}Immediately and permanently deletes the specified thread. Any messages that belong to the thread are also deleted. This operation cannot be undone. Prefer `thre
POST/gmail/v1/users/{userId}/threads/{id}/modifyModifies the labels applied to the thread. This applies to all messages in the thread.
POST/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.
POST/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.
POST/gmail/v1/users/{userId}/watchSet up or update a push notification watch on the given user mailbox.

Questions

Does the Gmail API API need an API key?

Yes. The Gmail API API uses OAuth authentication; the documentation explains how to get credentials.

Does the Gmail API API support HTTPS?

Yes, the Gmail API API is served over HTTPS.

How many endpoints does the Gmail API API have?

Its OpenAPI description lists 79 endpoints in version v1. All of them are shown on this page.

What are alternatives to the Gmail API API?

Other Analytics APIs include Google Play Integrity API, versionhistory.googleapis.com API, Doc Converter, Perspective Comment Analyzer API, Safe Browsing API.

Compare alternatives →

Google Play Integrity API

Analytics

The Play Integrity API helps you check that you're interacting with your genuine app on a genuine Android device powered by Google Play services. The Play Integrity API has replaced SafetyNet Attestation and Android Device Verification.

OAuth1 endpoints

versionhistory.googleapis.com API

Analytics

Version History API - Prod

No auth4 endpoints

Doc Converter

Analytics

This api converts file formats of OpenXml and OpenOffice documents formats to vector files (e.g., svg)

No auth1 endpoints

Perspective Comment Analyzer API

Analytics

The Perspective Comment Analyzer API provides information about the potential impact of a comment on a conversation (e.g. it can provide a score for the "toxicity" of a comment). Users can leverage the "SuggestCommentScore" method to submit corrections to improve Perspective over time. Users can set the "doNotStore" flag to ensure that all submitted comments are automatically deleted after scores are returned.

OAuth2 endpoints

Safe Browsing API

Analytics

Enables client applications to check web resources (most commonly URLs) against Google-generated lists of unsafe web resources. The Safe Browsing APIs are for non-commercial use only. If you need to use APIs to detect malicious URLs for commercial purposes – meaning “for sale or revenue-generating purposes” – please refer to the Web Risk API.

No auth7 endpoints

Web Fonts Developer API

Analytics

The Google Web Fonts Developer API lets you retrieve information about web fonts served by Google.

No auth1 endpoints

Listed from APIs.guru (CC0).