6.9 KiB
Users - Gmail - Delegates
- Notes
- API documentation
- Definitions
- Aliases
- Delegator Banner
- Delegate Notification
- Create Gmail delegates
- Delete Gmail delegates
- Update Gmail delegates
- Display Gmail delegates
- Delete all delegates for a user
Notes
To use Gmail delegation, the delegator and delagatee must be in org units where mail delegation is enabled. In the admin console, go to Apps/Google Workspace/Gmail/User Settings.
API documentation
Definitions
<DomainName> ::= <String>(.<String>)+
<EmailAddress> ::= <String>@<DomainName>
<UniqueID> ::= id:<String>
<UserItem> ::= <EmailAddress>|<UniqueID>|<String>
<UserList> ::= "<UserItem>(,<UserItem>)*"
<UserEntity> ::=
<UserList> | <FileSelector> | <CSVkmdSelector> | <CSVDataSelector>
See: https://github.com/GAM-team/GAM/wiki/Collections-of-Users
<StorageBucketName> ::= <String>
<StorageObjectName> ::= <String>
<StorageBucketObjectName> ::=
https://storage.cloud.google.com/<StorageBucketName>/<StorageObjectName>|
https://storage.googleapis.com/<StorageBucketName>/<StorageObjectName>|
gs://<StorageBucketName>/<StorageObjectName>|
<StorageBucketName>/<StorageObjectName>
<UserGoogleDoc> ::=
<EmailAddress> <DriveFileIDEntity>|<DriveFileNameEntity>|(<SharedDriveEntity> <SharedDriveFileNameEntity>)
<NotifyMessageContent> ::=
(message|textmessage|htmlmessage <String>)|
(file|textfile|htmlfile <FileName> [charset <Charset>])|
(gdoc|ghtml <UserGoogleDoc>)|
(gcsdoc|gcshtml <StorageBucketObjectName>)
Aliases
It is an error to use a user's alias as a delegate; if you try, an error will be generated.
The convertalias option causes GAM to make an extra API call per user in <UserEntity>
to convert aliases to primary email addresses. If you know that all of the email addresses
in <UserEntity> are primary, you can omit convertalias and avoid the extra API calls.
Delegator Banner
When creating a delegate, the following banner is displayed in the delegator's Gmail inbox, it can not be suppressed.
<Delegate> now has delegated access to your account. This notice will end in 7 days.
Delegate Notification
When creating a delegate, you can send a message to the delegate.
[notify [<Boolean>]
[subject <String>]
[from <EmailAaddress>] [mailbox <EmailAddress>]
[replyto <EmailAddress>]
[<NotifyMessageContent>] [html [<Boolean>]]
]
notify [<Boolean>]- Should notification be sent
In the subject and message, these strings will be replaced with the specified values:
#user#- user's email address#delegate#- delegate's email address
If subject is not specified, the following value will be used:
#user# mail delegation to #delegate#
<NotifyMessageContent> is the message, there are four ways to specify it:
message|textmessage|htmlmessage <String>- Use<String>as the messagefile|htmlfile <FileName> [charset <Charset>]- Read the message from<FileName>gdoc|ghtml <UserGoogleDoc>- Read the message from<UserGoogleDoc>gcsdoc|gcshtml <StorageBucketObjectName>- Read the message from the Google Cloud Storage file<StorageBucketObjectName>
If <NotifyMessageContent>is not specified, the following value will be used:
#user# has granted you #delegate# access to read, delete and send mail on their behalf.
Unless specified in <NotifyMessageContent>, messages are sent as plain text,
use html or html true to indicate that the message is HTML.
Use \n in message <String> to indicate a line break; no other special characters are recognized.
By default, the email is sent from the admin user identified in oauth2.txt, gam oauth info will show the value.
Use from <EmailAddress> to specify an alternate from address.
Use mailbox <EmailAddress> if from <EmailAddress> specifies a group; GAM has to login as a user to be able to send a message.
Gam gets no indication as to the status of the message delivery; the from user will get a non-delivery receipt if the message could not be sent to the delegate.
Create Gmail delegates
These two commands are equivalent.
gam <UserTypeEntity> add delegate|delegates [convertalias] <UserEntity>
[[notify <EmailAddressList>]
[subject <String>]
[from <EmailAaddress>] [mailbox <EmailAddress>]
[replyto <EmailAaddress>]
[<NotifyMessageContent>]
]
gam <UserTypeEntity> delegate|delegates to [convertalias] <UserEntity>
[[notify <EmailAddressList>]
[subject <String>]
[from <EmailAaddress>] [mailbox <EmailAddress>]
[replyto <EmailAaddress>]
[<NotifyMessageContent>]
]
Example
To give Bob access to Fred's mailbox as a delegate:
gam user fred@domain.com add delegate bob@domain.com
gam user fred@domain.com delegate to bob@domain.com
Delete Gmail delegates
gam <UserTypeEntity> delete|del delegate|delegates [convertalias] <UserEntity>
Update Gmail delegates
Update delegates to be able to access a user's contacts.
gam <UserTypeEntity> update delegate|delegates [convertalias] [<UserEntity>]
If <UserEntity> is omitted, all of a user's accepted delegates are updated.
Display Gmail delegates
gam <UserTypeEntity> show delegates|delegate [shownames] [csv]
gam <UserTypeEntity> print delegates|delegate [todrive <ToDriveAttribute>*] [shownames]
By default, delegate names are not displayed; use the shownames option to display the delegates name.
This involves an extra API call per delegate email address.
By default, show delegates displays indented keys and values; use the csv option to have just the values
shown as a comma separated list.
Delete all delegates for a user
$ gam redirect csv ./Delegates.csv user testsimple print delegates
Getting all Delegates for testsimple@domain.com
$ gam redirect stdout - multiprocess csv Delegates.csv gam user "~User" delete delegate "~delegateAddress"
2023-11-10T06:56:04.118-08:00,0/3,Using 3 processes...
2023-11-10T06:56:04.123-08:00,0,Processing item 3/3
User: testsimple@domain.com, Delete 1 Delegate
User: testsimple@domain.com, Delegate: testuser1@domain.com, Deleted
User: testsimple@domain.com, Delete 1 Delegate
User: testsimple@domain.com, Delegate: testuser2@domain.com, Deleted
User: testsimple@domain.com, Delete 1 Delegate
User: testsimple@domain.com, Delegate: testgroup@domain.com, Deleted
2023-11-10T06:56:07.253-08:00,0/3,Processing complete