Workspace and people

What you are allowed to do in the mailbox that is currently active: the role you hold, whether you own the workspace, and every permission that role grants. Read this before telling somebody a thing cannot be done. Tools you do not hold the permission for are not in your tool list at all, so an absent tool is more often a permission you lack than a feature this server is missing. It answers for the ACTIVE connection, so the answer changes after setActiveConnection. An app connected over OAuth also gets a last line saying how much of that the person gave the app, which addresses it reaches, and until when.

The roles this workspace defines and what each one grants. A role says what a person may DO, and with one exception it does not say which addresses they may do it to: that is a separate per-address grant, which listWorkspaceMembers reports. The exception is addresses:all, which reaches every address on every domain, including ones added later, for everybody who holds the role. Seeded roles come first; a workspace starts with six and may have renamed or deleted any but Owner, so do not assume a fixed set. Reports how many people and API keys hold each one, which is the fact that says whether changing it is safe. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

Who is in this workspace, the role each of them holds, and which addresses or whole domains they were given. Two different things per person and they are not interchangeable: the ROLE is what they may do, the ADDRESSES and DOMAINS are what they may do it to (a whole domain covers every address on it), and somebody can hold a role with no addresses (they see an empty mailbox, unless the role holds addresses:all, which reaches every address) or an address with no explicit role (an older grant, which implies one). The workspace owner is the first row, marked as the owner, and holds everything whatever their role says. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

Invitations to this workspace that nobody has accepted yet, by email: the role and the addresses or whole domains each will grant once accepted, when it expires, and whether the last email reached them. A role that holds addresses:all reaches every address on every domain whatever the invitation grants. A waiting invitation grants nothing until it is accepted. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

Withdraw an invitation that has not been accepted. Its link stops working at once and nothing it would have granted is granted. Inviting the same address again later sends a new one.

Send a waiting invitation again: a new link, fourteen more days, and the old link retired. The same address cannot be sent to twice within ten minutes. Anybody but the workspace owner is refused when the role it carries holds a permission this app may not use for them (a console-only one, such as billing, never can), or when it gives access to an address or a domain they do not reach themselves.

One role in full: its name, what it is for, every permission it grants and how many people and API keys hold it. A role says what somebody may do; which addresses they may do it to is a separate grant that listWorkspaceMembers reports.

Every permission a role can grant, with what it allows, the group it belongs to, and whether a key or an app can hold it. The console-only ones work for people and never for a key or an app. createRole and updateRole take these ids.

Create a role: a name and the permissions it grants, from listPermissions. Nobody holds it until setMemberRole or inviteMember hands it out. A role can never grant more than you hold yourself.

Rename a role, change its description, or replace the permissions it grants. permissions REPLACES the whole list, so name every permission the role should keep. The change reaches everybody and every API key holding the role on their next request. The owner role cannot be changed.

Delete a role. Anybody, any API key and any waiting invitation holding it moves to the role named in reassignTo; without one, a role somebody still holds is refused. The owner role cannot be deleted. This cannot be undone.

Invite somebody to this workspace by email, with a role and optionally the addresses or whole domains they may reach. They get an email with a link that lasts fourteen days, and they join with nothing until they accept. Somebody who is already a member is refused: setMemberRole changes what they may do.

Give a member of this workspace a different role. It changes what they may do and nothing about which addresses they reach. The owner keeps every permission and cannot be given a role, and the owner role cannot be handed out.

Remove somebody from this workspace: their role, every address and domain they were given, and every app they connected to it go at once. Their account stays. The owner cannot be removed.

Give a member one address, or change what they may do with one they already have: member reads it and sends as it, viewer only reads it. Sending also needs a role that may send. You can only give an address you reach yourself.

Take one address away from a member. They stay in the workspace with their role and their other addresses.

Give a member a whole domain: every address on it, including ones added later. member reads and sends, viewer only reads. You can only give a domain you reach yourself.

Take a whole domain away from a member. Addresses on it that were given to them one by one stay, and so do their role and their other grants.

The settings the app shows under Settings: time zone and formats, images, tracking, sounds and notifications, the blocklist and trusted senders, the signature, the workspace name, and the sender name and postal address the footer of broadcasts and automation emails shows. With address, the settings that apply to one address, a catch-all (*@domain) or a whole domain (@domain): its own signature, tracking and privacy choices, and the workspace's for the rest. overrides lists what that scope sets itself, and everything else is inherited.

Change settings, the way Settings does, with the same names getSettings reports. Without address it changes your account, the workspace name (workspaceName) and the workspace's privacy: external images, trusted senders, the blocklist, search by meaning (semanticSearch), suggested replies (replySuggestions), learning from replies (knowledgeLearning), and the sender name (marketingSenderName) and postal address (marketingPostalAddress) the footer of broadcasts and automation emails shows. With address it gives one address, a catch-all (*@domain) or a whole domain (@domain) a choice of its own: an address or a catch-all takes signature, openEmailSignature, trackOpens and trackClicks, external images, trusted senders and the blocklist, and a domain external images, trusted senders and the blocklist only. null removes a value the scope sets itself, so it inherits again. A value you leave out keeps what it had, and a list replaces the old one.

The out of office replies saved in the workspace, as the Out of office tab of each address shows them: whether each is on, whether it is answering mail right now, its dates, subject and message. With address, the reply of that one address or catch-all, which reads Off when none was saved.

Save the out of office reply of one address, or of a catch-all with *@domain, replacing what was saved. While it is active, each person who writes to the address gets the message once for the whole away period, as a reply in the same thread. Spam, newsletters and other bulk mail, automatic mail, bounces, blocked senders and the workspace's own addresses get no reply. startsAt and endsAt are ISO 8601 times: leave startsAt out to start now, or to keep the start of a reply that is already on, and endsAt out to keep it on until it is switched off. A new startsAt begins a new away period, in which everyone is answered once more. An empty subject answers with Re: and the subject received. contactsOnly answers only contacts and people the workspace has written to. enabled false keeps the text and stops the replies. getCurrentDate gives the time now.

Remove the saved out of office reply of one address or catch-all, so nothing is answered from it any more. To pause a reply and keep its text, use setOutOfOffice with enabled false instead.

The signatures saved in the workspace, as the Signature tab of each address shows them: the id, the address, the name, the HTML and what each is the default for. An address keeps a list of named signatures. One can be the default for new mail and one for replies and forwards, and sendEmail picks any of them with signatureId. With address, only the signatures of that address or catch-all.

Add a signature to one address, or to a catch-all with *@domain. html is the signature as HTML, such as <p>Ada Lovelace<br>Acme Ltd</p>, and is cleaned up on save. The first signature of an address becomes its default for new mail and for replies. A later one becomes a default only with isDefault or isReplyDefault true, and then takes that place from the one that held it. Names are unique per address.

Rename a signature, rewrite its HTML or change what it is the default for. Send only what changes. isDefault true makes it the signature of new mail from its address in place of the one that was, and false leaves new mail unsigned when this one was the default. isReplyDefault does the same for replies and forwards. listSignatures gives the ids.

Delete a signature for good. When it was a default, that default is left empty, so mail it would have signed goes out with no signature until another one is made the default with updateSignature.

Put a copy of a signature on other addresses or catch-alls. An address that already has a signature with the same name gets its HTML replaced, so copying again after an edit brings every copy up to date, and any other address gets a new signature. A copy becomes a default where isDefault or isReplyDefault is true, and on an address that had no signature at all.

The security log of the workspace, newest first: invitations sent and withdrawn, members added and removed, roles created, changed and deleted, the two-factor requirement, passwords set for an address and directory sync, each with who did it. Nothing is ever removed from it.