Google

Gmail API

Read, search and send Gmail as a signed-in user: threads, attachments, replies, drafts, labels, sync and push.

CommunicationGuided#email#gmail#google-workspace#oauth2#pubsub

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 is a REST interface to a user's Gmail mailbox: search and read messages and threads, send mail as the user (with attachments and in-thread replies), manage drafts and labels, and keep a copy in sync with history IDs and Pub/Sub push notifications. It is meant for apps acting for a signed-in user, not for bulk or marketing email. This guided collection covers the calls most apps need first; the generated Gmail listing on the Google page has every endpoint (settings, filters, delegates, S/MIME and more).

Get credentials, step by step

  1. Create or pick a project in the Google Cloud console.
  2. Enable the Gmail API for it.
  3. Configure the OAuth consent screen in Google Auth Platform: External user type, publishing status Testing, and add your own account as a test user.
  4. Create an OAuth client (Clients), type Desktop app or Web application, and copy its ID and secret into the collection variables.
  5. Get a token: either the OAuth 2.0 Playground (quickest), or the sign-in URL and code exchange in folder 1 of this collection.

Authentication and scopes

Every call sends Authorization: Bearer <access token>. Tokens last about an hour; the refresh token gets a new one. Most Gmail scopes are restricted (gmail.readonly, gmail.modify, gmail.compose, gmail.metadata, https://mail.google.com/): a public app that uses them must pass Google's verification and a yearly third-party security assessment. gmail.send is sensitive (verification, no assessment) and gmail.labels is non-sensitive. In Testing mode none of that is needed for your test users, but refresh tokens expire after 7 days. To try this whole collection, sign in with gmail.modify. See Choose Gmail API scopes.

Base URLs

  • https://gmail.googleapis.com/gmail/v1 for metadata calls ({{baseUrl}})
  • https://gmail.googleapis.com/upload/gmail/v1 for media uploads ({{uploadUrl}}), used for messages with attachments

User paths take an email address or me (the signed-in user).

How to use this collection

Fill clientId, clientSecret (and redirectUri if you changed it), get a token in folder 1, set toEmail, then run the folders in order. IDs flow between requests through test scripts: List messages stores messageId/threadId, Get a message stores the reply headers and attachmentId, Create a label stores labelId, Create a draft stores draftId.

Limits

The API is free to use but metered in quota units per user and per project per minute, and each method has a cost (sending costs far more than listing). Gmail's normal sending limits and per-message recipient limits apply too. Current numbers: Usage limits. On 429 or rate-limit 403s, retry with exponential backoff.

Common errors

StatusTypical reasonWhat to do
401Invalid Credentials / UNAUTHENTICATED: token missing, expired (about an hour) or revokedRun Refresh the access token; if that returns invalid_grant, sign in again
403insufficientPermissions / ACCESS_TOKEN_SCOPE_INSUFFICIENT: the token lacks the scope this request needsSign in again with the scope listed on the request; check with tokeninfo
403accessNotConfigured / SERVICE_DISABLED: the API is not enabled in this Cloud projectEnable it in the API Library, wait a few minutes
403 / 429rateLimitExceeded, userRateLimitExceeded, RESOURCE_EXHAUSTED: per-user or per-project quotaBack off exponentially and retry; spread work over time
404notFound: wrong ID, or the item belongs to another user / was deletedRe-run the list request that stores the ID
400invalid / badRequest / INVALID_ARGUMENT: malformed body or parameterRead error.message; it names the field

Links

Endpoints 25

1. Get an access token

  • POSTExchange the authorization code for tokenshttps://oauth2.googleapis.com/tokenSwaps the one-time code from the browser redirect for an access token (about an hour) and a refresh token (long-lived; 7 days while the app is in Testing).…
  • POSTRefresh the access tokenhttps://oauth2.googleapis.com/tokenGets a fresh access token from the stored refresh token, without the user signing in again. When: whenever a call returns 401 (access tokens last about an…
  • GETCheck which scopes the token has (tokeninfo)https://oauth2.googleapis.com/tokeninfoAsks Google what the current access token is good for: the granted scope list, the client it belongs to (aud/azp) and the seconds left (expires_in). When: a…

2. Read mail

  • GETGet the mailbox profile/users/me/profileReturns the signed-in user's email address, message and thread totals, and the mailbox's current historyId. When: right after getting a token, to check it…
  • GETList messages (search with q)/users/me/messagesLists message IDs, newest first, optionally filtered with the same search syntax as the Gmail search box. When: to find messages to open, label or sync. The…
  • GETGet a message (full, and how to decode the body)/users/me/messages/{{messageId}}Fetches one message with its headers and parsed MIME tree. When: after List messages (uses {{messageId}}). Scope: any of gmail.readonly, gmail.modify or…
  • GETGet message headers only (format=metadata)/users/me/messages/{{messageId}}Fetches only the labels and selected headers of a message, without the body. It costs less quota than full and works with the narrow gmail.metadata scope.…
  • GETList threads/users/me/threadsLists conversations (threads) instead of single messages, newest first. Takes the same q, labelIds, maxResults, pageToken and includeSpamTrash parameters as…
  • GETGet a thread/users/me/threads/{{threadId}}Fetches every message of a conversation in one call, oldest first. When: showing a conversation, or before replying to find the latest message's Message-ID.…
  • GETGet an attachment/users/me/messages/{{messageId}}/attachments/{{attachmentId}}Downloads one attachment of a message. When: a message part has body.attachmentId (files, and sometimes large inline parts). Get a message stores the first…

3. Send mail

  • POSTSend a plain-text email/users/me/messages/sendSends a new message to {{toEmail}}. When: transactional mail from the user's own account (notifications, follow-ups). This is not a bulk-mail service: Gmail's…
  • POSTSend an email with an attachment (multipart upload){{uploadUrl}}/users/me/messages/sendSends a message with a file attached, using the media upload endpoint (/upload/gmail/v1/users/me/messages/send) instead of a base64 raw field. The upload…
  • POSTReply in a thread/users/me/messages/sendSends a reply that Gmail shows inside the original conversation. When: after Get a message (it stores the threadId, the original Message-ID, Subject and…
  • POSTCreate a draft/users/me/draftsSaves a message as a draft (it appears in the user's Drafts folder) without sending it. When: your app prepares a message the user reviews and sends from…
  • POSTSend a draft/users/me/drafts/sendSends an existing draft. The draft is removed from Drafts and the message gets the SENT label. When: after Create a draft (uses {{draftId}}). Scope:…

4. Labels and organizing

  • GETList labels/users/me/labelsLists every system and user label in the mailbox. When: to map label names to IDs before filtering or modifying. Scope: gmail.labels, gmail.readonly,…
  • POSTCreate a label/users/me/labelsCreates a user label. When: your app files messages under its own label (e.g. Example Store/Orders; a / makes it a nested label in the Gmail UI). Scope:…
  • POSTMark read and add a label (modify)/users/me/messages/{{messageId}}/modifyAdds and removes labels on one message. This request marks {{messageId}} as read (removes UNREAD) and files it under {{labelId}}. When: after processing a…
  • POSTArchive a message/users/me/messages/{{messageId}}/modifyArchives a message by removing the INBOX label. The message stays in All Mail and under its other labels. When: "done" handling: the message leaves the inbox…
  • POSTModify many messages at once (batchModify)/users/me/messages/batchModifyAdds and removes labels on up to 1,000 messages in one call. When: bulk actions: mark everything from a search as read, archive a batch, label a set. Get the…
  • POSTMove a message to Trash/users/me/messages/{{messageId}}/trashMoves a message to Trash (adds TRASH, removes INBOX). Gmail deletes trashed messages for good after about 30 days. When: the user deletes a message in your…
  • POSTRestore a message from Trash/users/me/messages/{{messageId}}/untrashTakes a message out of Trash again (removes the TRASH label). When: an "undo" after Move a message to Trash. The message does not automatically get INBOX…

5. Sync and push notifications

  • GETList history (changes since historyId)/users/me/historyReturns the changes made to the mailbox after startHistoryId: messages added or deleted, labels added or removed. When: incremental sync, and after each push…
  • POSTWatch the mailbox (Pub/Sub push)/users/me/watchAsks Gmail to publish a notification to your Pub/Sub topic whenever the mailbox changes. When: instead of polling. Renew it at least every 7 days (once a day…
  • POSTStop push notifications/users/me/stopTurns off the mailbox's watch, so Gmail stops publishing to your topic. When: the user disconnects your app, or you move to another topic. Scope:…

API details

Base URL
https://gmail.googleapis.com/gmail/v1
https://gmail.googleapis.com/upload/gmail/v1
https://oauth2.googleapis.com
Authentication
A bearer token in the Authorization header
OAuth 2.0 (authorization code flow)
Operations
25 operations on 25 pathsPOST 15GET 10
Main resources
1. Get an access token 32. Read mail 73. Send mail 54. Labels and organizing 75. Sync and push notifications 3
Description format
Swastik Codes guided collection, API version checked against the docs on 2026-11-17

How to test the Gmail API 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 collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Exchange the authorization code for tokens” (POST https://oauth2.googleapis.com/token), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Gmail API?

Read, search and send Gmail as a signed-in user: threads, attachments, replies, drafts, labels, sync and push. It is listed under Communication and has 25 endpoints.

Who publishes the Gmail API?

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?

Its description lists 3 base URLs: https://gmail.googleapis.com/gmail/v1, https://gmail.googleapis.com/upload/gmail/v1, https://oauth2.googleapis.com. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the Gmail API?

It accepts 2 methods: A bearer token in the Authorization header; OAuth 2.0 (authorization code flow).

How many endpoints does the Gmail API have?

25 operations on 25 paths (15 POST, 10 GET). The largest groups are 1. Get an access token, 2. Read mail, 3. Send mail, 4. Labels and organizing.

Is forking the Gmail API 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.