Gmail API overview

The Gmail API is a RESTful API that lets you access Gmail mailboxes and send mail. For most web applications, the Gmail API is the best choice for authorized access to a user's Gmail data and is suitable for various applications, such as:

  • Read-only mail extraction, indexing, and backup
  • Automated or programmatic message sending
  • Email account migration
  • Email organization including filtering and sorting of messages
  • Standardization of email signatures across an organization

Common terms

The following is a list of common terms used in this API:

Delegator and Delegate
A delegator is a Gmail user who grants mailbox access to another user within the same Google Workspace organization. The user receiving this access is the delegate. Delegates can read, send, and delete messages, as well as view and add contacts on behalf of the delegator's account. For more information, see Manage delegates.
Draft
An unsent message. You can replace the message contained within the draft. Sending a draft automatically deletes the draft and creates a message with the SENT system label. The drafts resource represents a draft. For more information, see Work with drafts.
Filters
Advanced rules configured for an account that evaluate incoming messages against specific matching criteria (like sender, subject, or size). When a message matches, filters automatically trigger actions such as adding or removing labels, or forwarding the email to a specified address. For more information, see Manage filters.
Forwarding addresses
Specific, verified email addresses configured to receive auto-forwarded messages from a user's account. Before you can use an address in a forwarding rule or filter, you must register and verify it to prove ownership. For more information, see Manage forwarding.
Label

A mechanism for organizing messages and threads. For example, you can create the label "taxes" and apply it to all messages and threads related to taxes. For more information, see Manage labels.

There are two types of labels:

System labels
Internally created labels, such as INBOX, TRASH, or SPAM. You can't delete or modify these labels. However, you can apply or remove some system labels, such as INBOX, to or from messages and threads.
User labels
Labels created by a user. A user or an application can delete or modify these labels. The labels resource represents a user label.
Message

An email message containing the sender, recipients, subject, and body. After you create a message, you can't change it. The messages resource represents a message.

Push notifications

A server-side notification system integrating with Google Cloud Pub/Sub. Applications can "watch" a mailbox, and the Gmail API sends automatic webhooks or alerts whenever a change occurs (such as a new email arriving). This eliminates the need for your app to poll the server for updates. For more information, see Push notifications.

S/MIME certificates

Digital certificates uploaded to specific send-as aliases. These certificates let you send encrypted and digitally signed emails, ensuring message security and sender authenticity. For more information, see Manage S/MIME certificates.

Send-as aliases

These represent the various email addresses from which an account is authorized to send mail. Every account has at least one alias representing the primary email address. Aliases correspond to the "Send mail as" feature in the Gmail web interface and are also the basis for configuring per-address email signatures. For more information, see Manage aliases.

Thread

A collection of related messages forming a conversation. In an email client, a thread forms when one or more recipients respond to a message with their own message. For more information, see Manage threads.

  • To learn about developing with Google Workspace APIs, including handling authentication and authorization, refer to Develop on Google Workspace.

  • To learn how to configure and run a Gmail API app, read the Quickstarts.