API Reference

This API reference is organized by resource type. Each resource type has one or more data representations and one or more methods.

Resource types

  1. Users
  2. Users.drafts
  3. Users.history
  4. Users.labels
  5. Users.messages
  6. Users.messages.attachments
  7. Users.settings
  8. Users.settings.filters
  9. Users.settings.forwardingAddresses
  10. Users.settings.sendAs
  11. Users.threads
  12. Users.settings.sendAs.smimeInfo

Users

For Users Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
getProfile GET  /userId/profile Gets the current user's Gmail profile.
stop POST  /userId/stop Stop receiving push notifications for the given user mailbox.
watch POST  /userId/watch Set up or update a push notification watch on the given user mailbox.

Users.drafts

For Users.drafts Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
create POST
https://www.googleapis.com/upload/gmail/v1/users/userId/drafts

and
POST  /userId/drafts
Creates a new draft with the DRAFT label.
delete DELETE  /userId/drafts/id Immediately and permanently deletes the specified draft. Does not simply trash it.
get GET  /userId/drafts/id Gets the specified draft.
list GET  /userId/drafts Lists the drafts in the user's mailbox.
send POST
https://www.googleapis.com/upload/gmail/v1/users/userId/drafts/send

and
POST  /userId/drafts/send
Sends the specified, existing draft to the recipients in the To, Cc, and Bcc headers.
update PUT
https://www.googleapis.com/upload/gmail/v1/users/userId/drafts/id

and
PUT  /userId/drafts/id
Replaces a draft's content.

Users.history

For Users.history Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
list GET  /userId/history Lists the history of all changes to the given mailbox. History results are returned in chronological order (increasing historyId).

Users.labels

For Users.labels Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
create POST  /userId/labels Creates a new label.
delete DELETE  /userId/labels/id Immediately and permanently deletes the specified label and removes it from any messages and threads that it is applied to.
get GET  /userId/labels/id Gets the specified label.
list GET  /userId/labels Lists all labels in the user's mailbox.
patch PATCH  /userId/labels/id Updates the specified label. This method supports patch semantics.
update PUT  /userId/labels/id Updates the specified label.

Users.messages

For Users.messages Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
batchDelete POST  /userId/messages/batchDelete Deletes many messages by message ID. Provides no guarantees that messages were not already deleted or even existed at all.
batchModify POST  /userId/messages/batchModify Modifies the labels on the specified messages.
delete DELETE  /userId/messages/id Immediately and permanently deletes the specified message. This operation cannot be undone. Prefer messages.trash instead.
get GET  /userId/messages/id Gets the specified message.
import POST
https://www.googleapis.com/upload/gmail/v1/users/userId/messages/import

and
POST  /userId/messages/import
Imports a message into only this user's mailbox, with standard email delivery scanning and classification similar to receiving via SMTP. Does not send a message.
insert POST
https://www.googleapis.com/upload/gmail/v1/users/userId/messages

and
POST  /userId/messages
Directly inserts a message into only this user's mailbox similar to IMAP APPEND, bypassing most scanning and classification. Does not send a message.
list GET  /userId/messages Lists the messages in the user's mailbox.
modify POST  /userId/messages/id/modify Modifies the labels on the specified message.
send POST
https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send

and
POST  /userId/messages/send
Sends the specified message to the recipients in the To, Cc, and Bcc headers.
trash POST  /userId/messages/id/trash Moves the specified message to the trash.
untrash POST  /userId/messages/id/untrash Removes the specified message from the trash.

Users.messages.attachments

For Users.messages.attachments Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
get GET  /userId/messages/messageId/attachments/id Gets the specified message attachment.

Users.settings

For Users.settings Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
getAutoForwarding GET  /userId/settings/autoForwarding Gets the auto-forwarding setting for the specified account.
getImap GET  /userId/settings/imap Gets IMAP settings.
getPop GET  /userId/settings/pop Gets POP settings.
getVacation GET  /userId/settings/vacation Gets vacation responder settings.
updateAutoForwarding PUT  /userId/settings/autoForwarding Updates the auto-forwarding setting for the specified account. A verified forwarding address must be specified when auto-forwarding is enabled.

This method is only available to service account clients that have been delegated domain-wide authority.
updateImap PUT  /userId/settings/imap Updates IMAP settings.
updatePop PUT  /userId/settings/pop Updates POP settings.
updateVacation PUT  /userId/settings/vacation Updates vacation responder settings.

Users.settings.filters

For Users.settings.filters Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
create POST  /userId/settings/filters Creates a filter.
delete DELETE  /userId/settings/filters/id Deletes a filter.
get GET  /userId/settings/filters/id Gets a filter.
list GET  /userId/settings/filters Lists the message filters of a Gmail user.

Users.settings.forwardingAddresses

For Users.settings.forwardingAddresses Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
create POST  /userId/settings/forwardingAddresses Creates 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 to pending; otherwise, the resource will be created with verification status set to accepted.

This method is only available to service account clients that have been delegated domain-wide authority.
delete DELETE  /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 have been delegated domain-wide authority.
get GET  /userId/settings/forwardingAddresses/forwardingEmail Gets the specified forwarding address.
list GET  /userId/settings/forwardingAddresses Lists the forwarding addresses for the specified account.

Users.settings.sendAs

For Users.settings.sendAs Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
create POST  /userId/settings/sendAs Creates 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 creating the alias. If ownership verification is required for the alias, a message will be sent to the email address and the resource's verification status will be set to pending; otherwise, the resource will be created with verification status set to accepted. If a signature is provided, Gmail will sanitize the HTML before saving it with the alias.

This method is only available to service account clients that have been delegated domain-wide authority.
delete DELETE  /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 that have been delegated domain-wide authority.
get GET  /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.
list GET  /userId/settings/sendAs Lists 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" aliases.
patch PATCH  /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 the account can only be updated by service account clients that have been delegated domain-wide authority. This method supports patch semantics.
update PUT  /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 the account can only be updated by service account clients that have been delegated domain-wide authority.
verify POST  /userId/settings/sendAs/sendAsEmail/verify Sends a verification email to the specified send-as alias address. The verification status must be pending.

This method is only available to service account clients that have been delegated domain-wide authority.

Users.threads

For Users.threads Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
delete DELETE  /userId/threads/id Immediately and permanently deletes the specified thread. This operation cannot be undone. Prefer threads.trash instead.
get GET  /userId/threads/id Gets the specified thread.
list GET  /userId/threads Lists the threads in the user's mailbox.
modify POST  /userId/threads/id/modify Modifies the labels applied to the thread. This applies to all messages in the thread.
trash POST  /userId/threads/id/trash Moves the specified thread to the trash.
untrash POST  /userId/threads/id/untrash Removes the specified thread from the trash.

Users.settings.sendAs.smimeInfo

For Users.settings.sendAs.smimeInfo Resource details, see the resource representation page.

Method HTTP request Description
URIs relative to https://www.googleapis.com/gmail/v1/users, unless otherwise noted
delete DELETE  /userId/settings/sendAs/sendAsEmail/smimeInfo/id Deletes the specified S/MIME config for the specified send-as alias.
get GET  /userId/settings/sendAs/sendAsEmail/smimeInfo/id Gets the specified S/MIME config for the specified send-as alias.
insert POST  /userId/settings/sendAs/sendAsEmail/smimeInfo Insert (upload) the given S/MIME config for the specified send-as alias. Note that pkcs12 format is required for the key.
list GET  /userId/settings/sendAs/sendAsEmail/smimeInfo Lists S/MIME configs for the specified send-as alias.
setDefault POST  /userId/settings/sendAs/sendAsEmail/smimeInfo/id/setDefault Sets the default S/MIME config for the specified send-as alias.

Send feedback about...