Jump to Content
Product Announcements

New ways to manage delegate settings using the Gmail API

October 2, 2018
Andreas Ricci

Software Engineer, Gmail

Try Google Workspace at No Cost

Get a business email, all the storage you need, video conferencing, and more.


Today we’re extending the Gmail API by bringing G Suite developers new ways to manage the delegate settings of users in G Suite. With Gmail delegation, G Suite admins can grant access to a person’s mailbox to another person in their organization. For example, access to an executive’s mailbox can be granted to their administrative assistant.

With these new delegation methods, it’s possible for admin-authorized apps to add, view and delete Gmail delegates within a G Suite organization all within one place—the Gmail API. If you previously used the delegation methods in the Admin SDK’s Email Settings API that will soon no longer be available, these new methods are good replacements.

How delegation works in Gmail

Let’s say you want to allow an administrative assistant to access an executive’s mailbox. Gmail delegation is great for that. The person granting access (in this instance, the executive) is referred to as the delegator and the person receiving access (our assistant) is the delegate. With Gmail delegation, delegates can read, send and delete messages, as well as view and add contacts to the delegator's account. Read this article to learn more about mail delegation or how to manage delegates manually.

This also means that you can build tools and apps which (when authorized by G Suite admins) automate the Gmail delegation process. It’s now possible to set up or revoke delegate access to accounts quickly through open-source tools, such as the GAM command line tool, or through any other apps in your organization (including ones you may have built) that leverage these new methods.

With this update, we’re also providing additional functionality, like the ability to:

  • Create delegate relationships across multiple domains belonging to the same G Suite organization.

  • Delete pending and rejected delegate relationships.

  • Get the delegate relationship status of a particular user via the delegates.get method.

Getting started

As mentioned, the new Gmail delegate settings methods are restricted to G Suite users and can only be accessed through authorized service accounts with domain-wide authority. To try out the new methods, check out the documentation or use these reference materials for pointers. If you have any issues, you can also use the gmail-api tag on StackOverflow.

Note: If you previously used the delegation methods offered in the Email Settings API, here’s a migration guide to help you transition.

Posted in