--- title: "Workspace and people" description: "Who is asking, what they may do, and who else is here." url: "https://nextmail.sh/docs/mcp/tools/workspace" area: "MCP server" category: "Tools" --- # Workspace and people Who is asking, what they may do, and who else is here. ## Workspace and people tools | Tool | What it does | | --- | --- | | whoAmI | What you may do in the mailbox that is currently active: the role you hold, whether you own the workspace, and every permission that role grants. | | listRoles | The roles this workspace defines and what each one grants, with how many people and API keys hold each, the fact that says whether changing one is safe. Returned a page at a time. | | listWorkspaceMembers | Who is in the workspace, the role each of them holds, and which addresses they were given. Returned a page at a time. | | listInvitations | The invitations nobody has accepted yet: the role and the addresses each will grant, when it expires, and whether the email reached them. Returned a page at a time. | | revokeInvitation | Withdraw a waiting invitation. Its link stops working at once. A chat always asks first. | | resendInvitation | Send a waiting invitation again, with a new link and fourteen more days. | | getRole | One role in full: what it is for, every permission it grants and who holds it. | | listPermissions | Every permission a role can grant, its group, and whether a key or an app can hold it. | | createRole | Create a role from a name and the permissions it grants, never more than you hold yourself. | | updateRole | Rename a role, change its description, or replace its whole list of permissions. The owner role cannot be changed. | | deleteRole | Delete a role and move whoever holds it to the role in `reassignTo`. A chat always asks first. | | inviteMember | Invite somebody by email with a role and, if you like, addresses or whole domains. They join once they accept. | | setMemberRole | Give a member another role. Their addresses and domains stay as they are. | | removeMember | Take somebody out of the workspace with every grant they hold. A chat always asks first. | | grantMemberAddress | Give a member one address, as `member` or `viewer`, or change their access to it. | | revokeMemberAddress | Take one address back from a member. A chat always asks first. | | grantMemberDomain | Give a member a whole domain, every address on it including ones added later. | | revokeMemberDomain | Take a whole domain back from a member. A chat always asks first. | | getSettings | The settings the app shows under Settings, for the workspace and your account, or for one address with `address`. | | updateSettings | Change settings by the names `getSettings` reports, the sender name and postal address of the marketing footer included. With `address`, an address or a catch-all gets its own signature, tracking, external images, trusted senders and blocklist, and `@domain` its own external images, trusted senders and blocklist. `null` clears one. | | getOutOfOffice | The out of office replies saved in the workspace, or the one of a single address or catch-all. | | setOutOfOffice | Save the out of office reply of an address or a catch-all, with optional start and end times. Each sender is answered once per away period. | | clearOutOfOffice | Remove the saved out of office reply of an address or a catch-all. | | listSignatures | The signatures of every address, or of one address or catch-all: the name, the HTML and what each is the default for. | | createSignature | Add a named signature to an address or a catch-all. The first one becomes its default for new mail and for replies. | | updateSignature | Rename a signature, rewrite its HTML, or make it the default for new mail or for replies and forwards. | | deleteSignature | Delete a signature for good. A chat always asks first. | | copySignature | Put a copy of a signature on other addresses, replacing the one with the same name there. | | listWorkspaceSecurityEvents | The security log of the workspace, newest first: invitations, members, roles, the two-factor requirement, passwords set for an address and directory sync, each with who did it. Returned a page at a time. | > Read `whoAmI` before telling somebody a thing cannot be done. A tool you lack the permission for is not in your tool list AT ALL, so an absent tool is far more often a permission you do not hold than a feature this server is missing. It answers for the ACTIVE connection, so the answer changes after `setActiveConnection`. > `whoAmI` needs no permission. `listRoles`, `getRole` and `listPermissions` sit behind `roles:read` and the tools that change a role behind `roles:write`. `listWorkspaceMembers` and `listInvitations` sit behind `members:read`, and the tools that invite, change or remove somebody, or give and take back an address or a domain, behind `members:write`. Describing yourself is not a statement about anybody else, and the tools that name colleagues are gated like every other statement about somebody else. > A ROLE and an ADDRESS GRANT are two different things, and `listWorkspaceMembers` reports both per person because neither answers for the other. The role is what somebody may do, the addresses are what they may do it to, and a person can hold a role with no addresses (they open an empty mailbox, unless the role holds `addresses:all`, which reaches every address without a grant) or an address with no role row at all, which is an older grant that implies a role rather than one anybody chose. The workspace owner is not listed: they are the account the workspace belongs to and hold everything. > `roles:write` and `members:write` reach the whole workspace, so only a client connected with every address can be given them, and the tools that change roles and members act exactly as `/roles` and `/members` on the REST API do. A role can never grant more than your client may use itself, and anybody but the owner can only give addresses and domains they reach themselves. Anybody but the owner is refused `resendInvitation` when the invitation’s role holds a permission their client may not use, a console-only one included, or when it gives access to addresses or domains they do not reach themselves. > `deleteRole`, `removeMember`, `revokeMemberAddress` and `revokeMemberDomain` always show the person a card to approve in the assistant, and a client should ask first as well. The other tools that change roles and members run straight away when the person asked for the change. > Some tools on this server make a change the REST API guards with a verification code, and ask for the same code. Until the client has verified a code in the last 60 minutes, or the person has chosen Allow changes for 60 minutes on it in Account → Connected apps, such a tool answers with a result that starts `Refused (step_up_required):` and changes nothing. `emptyAudience` never asks for a code. The API Authentication page lists every tool that asks, and shows how to ask for a code and verify it. > `listWorkspaceSecurityEvents` sits behind `members:read`, like the other tools that name colleagues. The log is only ever read: no tool changes an entry or removes one. ## Reference ### `whoAmI` 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. - No scope. - MCP only, not in the app's assistant. - Toolkit: `core`. **Inputs** Takes no input. Also available in: API [`GET /addresses`](https://nextmail.sh/docs/api/reference/account#get-addresses), [`GET /keys/self`](https://nextmail.sh/docs/api/reference/account#get-keys-self); TypeScript [`nextmail.addresses.list()`](https://nextmail.sh/docs/sdk/reference/addresses#list), [`nextmail.addresses.listAll()`](https://nextmail.sh/docs/sdk/reference/addresses#listAll), [`nextmail.addresses.iterate()`](https://nextmail.sh/docs/sdk/reference/addresses#iterate), [`nextmail.me.get()`](https://nextmail.sh/docs/sdk/reference/me#get); Python [`addresses.list()`](https://nextmail.sh/docs/python/reference/addresses#list), [`addresses.list_all()`](https://nextmail.sh/docs/python/reference/addresses#listAll), [`addresses.iterate()`](https://nextmail.sh/docs/python/reference/addresses#iterate), [`me.get()`](https://nextmail.sh/docs/python/reference/me#get); Ruby [`addresses.list`](https://nextmail.sh/docs/ruby/reference/addresses#list), [`addresses.list_all`](https://nextmail.sh/docs/ruby/reference/addresses#listAll), [`addresses.iterate`](https://nextmail.sh/docs/ruby/reference/addresses#iterate), [`me.get`](https://nextmail.sh/docs/ruby/reference/me#get); PHP [`addresses->list`](https://nextmail.sh/docs/php/reference/addresses#list), [`addresses->listAll`](https://nextmail.sh/docs/php/reference/addresses#listAll), [`addresses->iterate`](https://nextmail.sh/docs/php/reference/addresses#iterate), [`me->get`](https://nextmail.sh/docs/php/reference/me#get); Go [`Addresses.List`](https://nextmail.sh/docs/go/reference/addresses#list), [`Addresses.ListAll`](https://nextmail.sh/docs/go/reference/addresses#listAll), [`Addresses.Iterate`](https://nextmail.sh/docs/go/reference/addresses#iterate), [`Me.Get`](https://nextmail.sh/docs/go/reference/me#get); Java [`addresses().list`](https://nextmail.sh/docs/java/reference/addresses#list), [`addresses().listAll`](https://nextmail.sh/docs/java/reference/addresses#listAll), [`addresses().iterate`](https://nextmail.sh/docs/java/reference/addresses#iterate), [`me().get`](https://nextmail.sh/docs/java/reference/me#get); C# [`Addresses.ListAsync`](https://nextmail.sh/docs/csharp/reference/addresses#list), [`Addresses.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/addresses#listAll), [`Addresses.IterateAsync`](https://nextmail.sh/docs/csharp/reference/addresses#iterate), [`Me.GetAsync`](https://nextmail.sh/docs/csharp/reference/me#get). ### `listRoles` 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. - Scopes: `roles:read`. - The app's assistant runs it without asking. - Toolkit: `workspace`. **Inputs** - `limit` (`integer`, at least 1, at most 100) - `cursor` (`string`) Also available in: API [`GET /domains`](https://nextmail.sh/docs/api/reference/domains#get-domains), [`GET /roles`](https://nextmail.sh/docs/api/reference/roles#get-roles), [`GET /roles/permissions`](https://nextmail.sh/docs/api/reference/roles#get-roles-permissions); TypeScript [`nextmail.domains.list()`](https://nextmail.sh/docs/sdk/reference/domains#list), [`nextmail.domains.listAll()`](https://nextmail.sh/docs/sdk/reference/domains#listAll), [`nextmail.domains.iterate()`](https://nextmail.sh/docs/sdk/reference/domains#iterate), [`nextmail.roles.list()`](https://nextmail.sh/docs/sdk/reference/roles#list), [`nextmail.roles.listAll()`](https://nextmail.sh/docs/sdk/reference/roles#listAll), [`nextmail.roles.iterate()`](https://nextmail.sh/docs/sdk/reference/roles#iterate), [`nextmail.roles.listPermissions()`](https://nextmail.sh/docs/sdk/reference/roles#listPermissions); Python [`domains.list()`](https://nextmail.sh/docs/python/reference/domains#list), [`domains.list_all()`](https://nextmail.sh/docs/python/reference/domains#listAll), [`domains.iterate()`](https://nextmail.sh/docs/python/reference/domains#iterate), [`roles.list()`](https://nextmail.sh/docs/python/reference/roles#list), [`roles.list_all()`](https://nextmail.sh/docs/python/reference/roles#listAll), [`roles.iterate()`](https://nextmail.sh/docs/python/reference/roles#iterate), [`roles.list_permissions()`](https://nextmail.sh/docs/python/reference/roles#listPermissions); Ruby [`domains.list`](https://nextmail.sh/docs/ruby/reference/domains#list), [`domains.list_all`](https://nextmail.sh/docs/ruby/reference/domains#listAll), [`domains.iterate`](https://nextmail.sh/docs/ruby/reference/domains#iterate), [`roles.list`](https://nextmail.sh/docs/ruby/reference/roles#list), [`roles.list_all`](https://nextmail.sh/docs/ruby/reference/roles#listAll), [`roles.iterate`](https://nextmail.sh/docs/ruby/reference/roles#iterate), [`roles.list_permissions`](https://nextmail.sh/docs/ruby/reference/roles#listPermissions); PHP [`domains->list`](https://nextmail.sh/docs/php/reference/domains#list), [`domains->listAll`](https://nextmail.sh/docs/php/reference/domains#listAll), [`domains->iterate`](https://nextmail.sh/docs/php/reference/domains#iterate), [`roles->list`](https://nextmail.sh/docs/php/reference/roles#list), [`roles->listAll`](https://nextmail.sh/docs/php/reference/roles#listAll), [`roles->iterate`](https://nextmail.sh/docs/php/reference/roles#iterate), [`roles->listPermissions`](https://nextmail.sh/docs/php/reference/roles#listPermissions); Go [`Domains.List`](https://nextmail.sh/docs/go/reference/domains#list), [`Domains.ListAll`](https://nextmail.sh/docs/go/reference/domains#listAll), [`Domains.Iterate`](https://nextmail.sh/docs/go/reference/domains#iterate), [`Roles.List`](https://nextmail.sh/docs/go/reference/roles#list), [`Roles.ListAll`](https://nextmail.sh/docs/go/reference/roles#listAll), [`Roles.Iterate`](https://nextmail.sh/docs/go/reference/roles#iterate), [`Roles.ListPermissions`](https://nextmail.sh/docs/go/reference/roles#listPermissions); Java [`domains().list`](https://nextmail.sh/docs/java/reference/domains#list), [`domains().listAll`](https://nextmail.sh/docs/java/reference/domains#listAll), [`domains().iterate`](https://nextmail.sh/docs/java/reference/domains#iterate), [`roles().list`](https://nextmail.sh/docs/java/reference/roles#list), [`roles().listAll`](https://nextmail.sh/docs/java/reference/roles#listAll), [`roles().iterate`](https://nextmail.sh/docs/java/reference/roles#iterate), [`roles().listPermissions`](https://nextmail.sh/docs/java/reference/roles#listPermissions); C# [`Domains.ListAsync`](https://nextmail.sh/docs/csharp/reference/domains#list), [`Domains.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/domains#listAll), [`Domains.IterateAsync`](https://nextmail.sh/docs/csharp/reference/domains#iterate), [`Roles.ListAsync`](https://nextmail.sh/docs/csharp/reference/roles#list), [`Roles.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/roles#listAll), [`Roles.IterateAsync`](https://nextmail.sh/docs/csharp/reference/roles#iterate), [`Roles.ListPermissionsAsync`](https://nextmail.sh/docs/csharp/reference/roles#listPermissions). ### `listWorkspaceMembers` 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. - Scopes: `members:read`. - The app's assistant runs it without asking. - Toolkit: `workspace`. **Inputs** - `limit` (`integer`, at least 1, at most 100) - `cursor` (`string`) Also available in: API [`GET /members`](https://nextmail.sh/docs/api/reference/members#get-members), [`GET /members/{userId}`](https://nextmail.sh/docs/api/reference/members#get-members-userid); TypeScript [`nextmail.members.list()`](https://nextmail.sh/docs/sdk/reference/members#list), [`nextmail.members.listAll()`](https://nextmail.sh/docs/sdk/reference/members#listAll), [`nextmail.members.iterate()`](https://nextmail.sh/docs/sdk/reference/members#iterate), [`nextmail.members.get()`](https://nextmail.sh/docs/sdk/reference/members#get); Python [`members.list()`](https://nextmail.sh/docs/python/reference/members#list), [`members.list_all()`](https://nextmail.sh/docs/python/reference/members#listAll), [`members.iterate()`](https://nextmail.sh/docs/python/reference/members#iterate), [`members.get()`](https://nextmail.sh/docs/python/reference/members#get); Ruby [`members.list`](https://nextmail.sh/docs/ruby/reference/members#list), [`members.list_all`](https://nextmail.sh/docs/ruby/reference/members#listAll), [`members.iterate`](https://nextmail.sh/docs/ruby/reference/members#iterate), [`members.get`](https://nextmail.sh/docs/ruby/reference/members#get); PHP [`members->list`](https://nextmail.sh/docs/php/reference/members#list), [`members->listAll`](https://nextmail.sh/docs/php/reference/members#listAll), [`members->iterate`](https://nextmail.sh/docs/php/reference/members#iterate), [`members->get`](https://nextmail.sh/docs/php/reference/members#get); Go [`Members.List`](https://nextmail.sh/docs/go/reference/members#list), [`Members.ListAll`](https://nextmail.sh/docs/go/reference/members#listAll), [`Members.Iterate`](https://nextmail.sh/docs/go/reference/members#iterate), [`Members.Get`](https://nextmail.sh/docs/go/reference/members#get); Java [`members().list`](https://nextmail.sh/docs/java/reference/members#list), [`members().listAll`](https://nextmail.sh/docs/java/reference/members#listAll), [`members().iterate`](https://nextmail.sh/docs/java/reference/members#iterate), [`members().get`](https://nextmail.sh/docs/java/reference/members#get); C# [`Members.ListAsync`](https://nextmail.sh/docs/csharp/reference/members#list), [`Members.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/members#listAll), [`Members.IterateAsync`](https://nextmail.sh/docs/csharp/reference/members#iterate), [`Members.GetAsync`](https://nextmail.sh/docs/csharp/reference/members#get). ### `listInvitations` 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. - Scopes: `members:read`. - The app's assistant runs it without asking. - Toolkit: `workspace`. **Inputs** - `limit` (`integer`, at least 1, at most 100) - `cursor` (`string`) Also available in: API [`GET /members/invitations`](https://nextmail.sh/docs/api/reference/members#get-members-invitations); TypeScript [`nextmail.members.listInvitations()`](https://nextmail.sh/docs/sdk/reference/members#listInvitations), [`nextmail.members.listAllInvitations()`](https://nextmail.sh/docs/sdk/reference/members#listAllInvitations), [`nextmail.members.iterateInvitations()`](https://nextmail.sh/docs/sdk/reference/members#iterateInvitations); Python [`members.list_invitations()`](https://nextmail.sh/docs/python/reference/members#listInvitations), [`members.list_all_invitations()`](https://nextmail.sh/docs/python/reference/members#listAllInvitations), [`members.iterate_invitations()`](https://nextmail.sh/docs/python/reference/members#iterateInvitations); Ruby [`members.list_invitations`](https://nextmail.sh/docs/ruby/reference/members#listInvitations), [`members.list_all_invitations`](https://nextmail.sh/docs/ruby/reference/members#listAllInvitations), [`members.iterate_invitations`](https://nextmail.sh/docs/ruby/reference/members#iterateInvitations); PHP [`members->listInvitations`](https://nextmail.sh/docs/php/reference/members#listInvitations), [`members->listAllInvitations`](https://nextmail.sh/docs/php/reference/members#listAllInvitations), [`members->iterateInvitations`](https://nextmail.sh/docs/php/reference/members#iterateInvitations); Go [`Members.ListInvitations`](https://nextmail.sh/docs/go/reference/members#listInvitations), [`Members.ListAllInvitations`](https://nextmail.sh/docs/go/reference/members#listAllInvitations), [`Members.IterateInvitations`](https://nextmail.sh/docs/go/reference/members#iterateInvitations); Java [`members().listInvitations`](https://nextmail.sh/docs/java/reference/members#listInvitations), [`members().listAllInvitations`](https://nextmail.sh/docs/java/reference/members#listAllInvitations), [`members().iterateInvitations`](https://nextmail.sh/docs/java/reference/members#iterateInvitations); C# [`Members.ListInvitationsAsync`](https://nextmail.sh/docs/csharp/reference/members#listInvitations), [`Members.ListAllInvitationsAsync`](https://nextmail.sh/docs/csharp/reference/members#listAllInvitations), [`Members.IterateInvitationsAsync`](https://nextmail.sh/docs/csharp/reference/members#iterateInvitations). ### `revokeInvitation` 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. - Scopes: `members:write`. - The app's assistant always asks first. - Toolkit: `workspace`. **Inputs** - `invitationId` (`string`, required, not empty) Also available in: API [`DELETE /members/invitations/{invitationId}`](https://nextmail.sh/docs/api/reference/members#delete-members-invitations-invitationid); TypeScript [`nextmail.members.revokeInvitation()`](https://nextmail.sh/docs/sdk/reference/members#revokeInvitation); Python [`members.revoke_invitation()`](https://nextmail.sh/docs/python/reference/members#revokeInvitation); Ruby [`members.revoke_invitation`](https://nextmail.sh/docs/ruby/reference/members#revokeInvitation); PHP [`members->revokeInvitation`](https://nextmail.sh/docs/php/reference/members#revokeInvitation); Go [`Members.RevokeInvitation`](https://nextmail.sh/docs/go/reference/members#revokeInvitation); Java [`members().revokeInvitation`](https://nextmail.sh/docs/java/reference/members#revokeInvitation); C# [`Members.RevokeInvitationAsync`](https://nextmail.sh/docs/csharp/reference/members#revokeInvitation). ### `resendInvitation` 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. - Scopes: `members:write`. - The app's assistant asks first unless you asked for it. - Toolkit: `workspace`. **Inputs** - `invitationId` (`string`, required, not empty) Also available in: API [`POST /members/invitations/{invitationId}/resend`](https://nextmail.sh/docs/api/reference/members#post-members-invitations-invitationid-resend); TypeScript [`nextmail.members.resendInvitation()`](https://nextmail.sh/docs/sdk/reference/members#resendInvitation); Python [`members.resend_invitation()`](https://nextmail.sh/docs/python/reference/members#resendInvitation); Ruby [`members.resend_invitation`](https://nextmail.sh/docs/ruby/reference/members#resendInvitation); PHP [`members->resendInvitation`](https://nextmail.sh/docs/php/reference/members#resendInvitation); Go [`Members.ResendInvitation`](https://nextmail.sh/docs/go/reference/members#resendInvitation); Java [`members().resendInvitation`](https://nextmail.sh/docs/java/reference/members#resendInvitation); C# [`Members.ResendInvitationAsync`](https://nextmail.sh/docs/csharp/reference/members#resendInvitation). ### `getRole` 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. - Scopes: `roles:read`. - The app's assistant runs it without asking. - Toolkit: `workspace`. **Inputs** - `id` (`string`, required, 1 to 128 characters): The role, by its id (role_…). listRoles names every one. Also available in: API [`GET /roles/{id}`](https://nextmail.sh/docs/api/reference/roles#get-roles-id); TypeScript [`nextmail.roles.get()`](https://nextmail.sh/docs/sdk/reference/roles#get); Python [`roles.get()`](https://nextmail.sh/docs/python/reference/roles#get); Ruby [`roles.get`](https://nextmail.sh/docs/ruby/reference/roles#get); PHP [`roles->get`](https://nextmail.sh/docs/php/reference/roles#get); Go [`Roles.Get`](https://nextmail.sh/docs/go/reference/roles#get); Java [`roles().get`](https://nextmail.sh/docs/java/reference/roles#get); C# [`Roles.GetAsync`](https://nextmail.sh/docs/csharp/reference/roles#get). ### `listPermissions` 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. - Scopes: `roles:read`. - The app's assistant runs it without asking. - Toolkit: `workspace`. **Inputs** Takes no input. Also available in: API [`GET /roles/permissions`](https://nextmail.sh/docs/api/reference/roles#get-roles-permissions); TypeScript [`nextmail.roles.listPermissions()`](https://nextmail.sh/docs/sdk/reference/roles#listPermissions); Python [`roles.list_permissions()`](https://nextmail.sh/docs/python/reference/roles#listPermissions); Ruby [`roles.list_permissions`](https://nextmail.sh/docs/ruby/reference/roles#listPermissions); PHP [`roles->listPermissions`](https://nextmail.sh/docs/php/reference/roles#listPermissions); Go [`Roles.ListPermissions`](https://nextmail.sh/docs/go/reference/roles#listPermissions); Java [`roles().listPermissions`](https://nextmail.sh/docs/java/reference/roles#listPermissions); C# [`Roles.ListPermissionsAsync`](https://nextmail.sh/docs/csharp/reference/roles#listPermissions). ### `createRole` 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. - Scopes: `roles:write`. - The app's assistant always asks first. - Toolkit: `workspace`. **Inputs** - `name` (`string`, required, 1 to 48 characters) - `description` (`string`, up to 240 characters) - `permissions` (`string[]`, required, up to 53 items) Also available in: API [`POST /roles`](https://nextmail.sh/docs/api/reference/roles#post-roles); TypeScript [`nextmail.roles.create()`](https://nextmail.sh/docs/sdk/reference/roles#create); Python [`roles.create()`](https://nextmail.sh/docs/python/reference/roles#create); Ruby [`roles.create`](https://nextmail.sh/docs/ruby/reference/roles#create); PHP [`roles->create`](https://nextmail.sh/docs/php/reference/roles#create); Go [`Roles.Create`](https://nextmail.sh/docs/go/reference/roles#create); Java [`roles().create`](https://nextmail.sh/docs/java/reference/roles#create); C# [`Roles.CreateAsync`](https://nextmail.sh/docs/csharp/reference/roles#create). ### `updateRole` 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. - Scopes: `roles:write`. - The app's assistant always asks first. - Asks for a verification code, the same as [`PATCH /roles/{id}`](https://nextmail.sh/docs/api/reference/roles#patch-roles-id). - Toolkit: `workspace`. **Inputs** - `id` (`string`, required, 1 to 128 characters): The role, by its id (role_…). listRoles names every one. - `name` (`string`, 1 to 48 characters) - `description` (`string`, nullable, up to 240 characters) - `permissions` (`string[]`, up to 53 items) Also available in: API [`PATCH /roles/{id}`](https://nextmail.sh/docs/api/reference/roles#patch-roles-id); TypeScript [`nextmail.roles.update()`](https://nextmail.sh/docs/sdk/reference/roles#update); Python [`roles.update()`](https://nextmail.sh/docs/python/reference/roles#update); Ruby [`roles.update`](https://nextmail.sh/docs/ruby/reference/roles#update); PHP [`roles->update`](https://nextmail.sh/docs/php/reference/roles#update); Go [`Roles.Update`](https://nextmail.sh/docs/go/reference/roles#update); Java [`roles().update`](https://nextmail.sh/docs/java/reference/roles#update); C# [`Roles.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/roles#update). ### `deleteRole` 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. - Scopes: `roles:write`. - The app's assistant always asks first. - Asks for a verification code, the same as [`DELETE /roles/{id}`](https://nextmail.sh/docs/api/reference/roles#delete-roles-id). - Toolkit: `workspace`. **Inputs** - `id` (`string`, required, 1 to 128 characters): The role, by its id (role_…). listRoles names every one. - `reassignTo` (`string`, 1 to 128 characters): The role its holders move to, by id. Also available in: API [`DELETE /roles/{id}`](https://nextmail.sh/docs/api/reference/roles#delete-roles-id); TypeScript [`nextmail.roles.delete()`](https://nextmail.sh/docs/sdk/reference/roles#delete); Python [`roles.delete()`](https://nextmail.sh/docs/python/reference/roles#delete); Ruby [`roles.delete`](https://nextmail.sh/docs/ruby/reference/roles#delete); PHP [`roles->delete`](https://nextmail.sh/docs/php/reference/roles#delete); Go [`Roles.Delete`](https://nextmail.sh/docs/go/reference/roles#delete); Java [`roles().delete`](https://nextmail.sh/docs/java/reference/roles#delete); C# [`Roles.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/roles#delete). ### `inviteMember` 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. - Scopes: `members:write`. - The app's assistant always asks first. - Asks for a verification code, the same as [`POST /members`](https://nextmail.sh/docs/api/reference/members#post-members). - Toolkit: `workspace`. **Inputs** - `email` (`string`, required, format `email`) - `roleId` (`string`, required, 1 to 128 characters): The role, by its id (role_…). listRoles names every one. - `addressIds` (`string[]`, up to 64 items) - `domainIds` (`string[]`, up to 64 items) - `access` (`string`, one of `"member"`, `"viewer"`, default `"member"`): member reads and sends as it, viewer only reads it. Left out, member. Also available in: API [`POST /members`](https://nextmail.sh/docs/api/reference/members#post-members); TypeScript [`nextmail.members.add()`](https://nextmail.sh/docs/sdk/reference/members#add); Python [`members.add()`](https://nextmail.sh/docs/python/reference/members#add); Ruby [`members.add`](https://nextmail.sh/docs/ruby/reference/members#add); PHP [`members->add`](https://nextmail.sh/docs/php/reference/members#add); Go [`Members.Add`](https://nextmail.sh/docs/go/reference/members#add); Java [`members().add`](https://nextmail.sh/docs/java/reference/members#add); C# [`Members.AddAsync`](https://nextmail.sh/docs/csharp/reference/members#add). ### `setMemberRole` 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. - Scopes: `members:write`. - The app's assistant always asks first. - Asks for a verification code, the same as [`PATCH /members/{userId}`](https://nextmail.sh/docs/api/reference/members#patch-members-userid). - Toolkit: `workspace`. **Inputs** - `userId` (`string`, required, 1 to 128 characters): The account id of the person, the User ID listWorkspaceMembers reports. Never an email address. - `roleId` (`string`, required, 1 to 128 characters): The role, by its id (role_…). listRoles names every one. Also available in: API [`PATCH /members/{userId}`](https://nextmail.sh/docs/api/reference/members#patch-members-userid); TypeScript [`nextmail.members.update()`](https://nextmail.sh/docs/sdk/reference/members#update); Python [`members.update()`](https://nextmail.sh/docs/python/reference/members#update); Ruby [`members.update`](https://nextmail.sh/docs/ruby/reference/members#update); PHP [`members->update`](https://nextmail.sh/docs/php/reference/members#update); Go [`Members.Update`](https://nextmail.sh/docs/go/reference/members#update); Java [`members().update`](https://nextmail.sh/docs/java/reference/members#update); C# [`Members.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/members#update). ### `removeMember` 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. - Scopes: `members:write`. - The app's assistant always asks first. - Asks for a verification code, the same as [`DELETE /members/{userId}`](https://nextmail.sh/docs/api/reference/members#delete-members-userid). - Toolkit: `workspace`. **Inputs** - `userId` (`string`, required, 1 to 128 characters): The account id of the person, the User ID listWorkspaceMembers reports. Never an email address. Also available in: API [`DELETE /members/{userId}`](https://nextmail.sh/docs/api/reference/members#delete-members-userid); TypeScript [`nextmail.members.remove()`](https://nextmail.sh/docs/sdk/reference/members#remove); Python [`members.remove()`](https://nextmail.sh/docs/python/reference/members#remove); Ruby [`members.remove`](https://nextmail.sh/docs/ruby/reference/members#remove); PHP [`members->remove`](https://nextmail.sh/docs/php/reference/members#remove); Go [`Members.Remove`](https://nextmail.sh/docs/go/reference/members#remove); Java [`members().remove`](https://nextmail.sh/docs/java/reference/members#remove); C# [`Members.RemoveAsync`](https://nextmail.sh/docs/csharp/reference/members#remove). ### `grantMemberAddress` 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. - Scopes: `members:write`. - The app's assistant always asks first. - Asks for a verification code, the same as [`POST /members/{userId}/addresses`](https://nextmail.sh/docs/api/reference/members#post-members-userid-addresses). - Toolkit: `workspace`. **Inputs** - `userId` (`string`, required, 1 to 128 characters): The account id of the person, the User ID listWorkspaceMembers reports. Never an email address. - `addressId` (`string`, required, 1 to 128 characters) - `access` (`string`, one of `"member"`, `"viewer"`, default `"member"`): member reads and sends as it, viewer only reads it. Left out, member. Also available in: API [`POST /members/{userId}/addresses`](https://nextmail.sh/docs/api/reference/members#post-members-userid-addresses); TypeScript [`nextmail.members.grantAddress()`](https://nextmail.sh/docs/sdk/reference/members#grantAddress); Python [`members.grant_address()`](https://nextmail.sh/docs/python/reference/members#grantAddress); Ruby [`members.grant_address`](https://nextmail.sh/docs/ruby/reference/members#grantAddress); PHP [`members->grantAddress`](https://nextmail.sh/docs/php/reference/members#grantAddress); Go [`Members.GrantAddress`](https://nextmail.sh/docs/go/reference/members#grantAddress); Java [`members().grantAddress`](https://nextmail.sh/docs/java/reference/members#grantAddress); C# [`Members.GrantAddressAsync`](https://nextmail.sh/docs/csharp/reference/members#grantAddress). ### `revokeMemberAddress` Take one address away from a member. They stay in the workspace with their role and their other addresses. - Scopes: `members:write`. - The app's assistant always asks first. - Asks for a verification code, the same as [`DELETE /members/{userId}/addresses/{addressId}`](https://nextmail.sh/docs/api/reference/members#delete-members-userid-addresses-addressid). - Toolkit: `workspace`. **Inputs** - `userId` (`string`, required, 1 to 128 characters): The account id of the person, the User ID listWorkspaceMembers reports. Never an email address. - `addressId` (`string`, required, 1 to 128 characters) Also available in: API [`DELETE /members/{userId}/addresses/{addressId}`](https://nextmail.sh/docs/api/reference/members#delete-members-userid-addresses-addressid); TypeScript [`nextmail.members.revokeAddress()`](https://nextmail.sh/docs/sdk/reference/members#revokeAddress); Python [`members.revoke_address()`](https://nextmail.sh/docs/python/reference/members#revokeAddress); Ruby [`members.revoke_address`](https://nextmail.sh/docs/ruby/reference/members#revokeAddress); PHP [`members->revokeAddress`](https://nextmail.sh/docs/php/reference/members#revokeAddress); Go [`Members.RevokeAddress`](https://nextmail.sh/docs/go/reference/members#revokeAddress); Java [`members().revokeAddress`](https://nextmail.sh/docs/java/reference/members#revokeAddress); C# [`Members.RevokeAddressAsync`](https://nextmail.sh/docs/csharp/reference/members#revokeAddress). ### `grantMemberDomain` 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. - Scopes: `members:write`. - The app's assistant always asks first. - Asks for a verification code, the same as [`POST /members/{userId}/domains`](https://nextmail.sh/docs/api/reference/members#post-members-userid-domains). - Toolkit: `workspace`. **Inputs** - `userId` (`string`, required, 1 to 128 characters): The account id of the person, the User ID listWorkspaceMembers reports. Never an email address. - `domainId` (`string`, required, 1 to 128 characters) - `access` (`string`, one of `"member"`, `"viewer"`, default `"member"`): member reads and sends as it, viewer only reads it. Left out, member. Also available in: API [`POST /members/{userId}/domains`](https://nextmail.sh/docs/api/reference/members#post-members-userid-domains); TypeScript [`nextmail.members.grantDomain()`](https://nextmail.sh/docs/sdk/reference/members#grantDomain); Python [`members.grant_domain()`](https://nextmail.sh/docs/python/reference/members#grantDomain); Ruby [`members.grant_domain`](https://nextmail.sh/docs/ruby/reference/members#grantDomain); PHP [`members->grantDomain`](https://nextmail.sh/docs/php/reference/members#grantDomain); Go [`Members.GrantDomain`](https://nextmail.sh/docs/go/reference/members#grantDomain); Java [`members().grantDomain`](https://nextmail.sh/docs/java/reference/members#grantDomain); C# [`Members.GrantDomainAsync`](https://nextmail.sh/docs/csharp/reference/members#grantDomain). ### `revokeMemberDomain` 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. - Scopes: `members:write`. - The app's assistant always asks first. - Asks for a verification code, the same as [`DELETE /members/{userId}/domains/{domainId}`](https://nextmail.sh/docs/api/reference/members#delete-members-userid-domains-domainid). - Toolkit: `workspace`. **Inputs** - `userId` (`string`, required, 1 to 128 characters): The account id of the person, the User ID listWorkspaceMembers reports. Never an email address. - `domainId` (`string`, required, 1 to 128 characters) Also available in: API [`DELETE /members/{userId}/domains/{domainId}`](https://nextmail.sh/docs/api/reference/members#delete-members-userid-domains-domainid); TypeScript [`nextmail.members.revokeDomain()`](https://nextmail.sh/docs/sdk/reference/members#revokeDomain); Python [`members.revoke_domain()`](https://nextmail.sh/docs/python/reference/members#revokeDomain); Ruby [`members.revoke_domain`](https://nextmail.sh/docs/ruby/reference/members#revokeDomain); PHP [`members->revokeDomain`](https://nextmail.sh/docs/php/reference/members#revokeDomain); Go [`Members.RevokeDomain`](https://nextmail.sh/docs/go/reference/members#revokeDomain); Java [`members().revokeDomain`](https://nextmail.sh/docs/java/reference/members#revokeDomain); C# [`Members.RevokeDomainAsync`](https://nextmail.sh/docs/csharp/reference/members#revokeDomain). ### `getSettings` 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. - Scopes: `settings:read`. - The app's assistant runs it without asking. - Toolkit: `workspace`. **Inputs** - `address` (`string`, 3 to 320 characters): One address, such as hello@example.com, *@example.com for the catch-all of a domain, or @example.com for a whole domain. Also available in: API [`GET /settings`](https://nextmail.sh/docs/api/reference/settings#get-settings); TypeScript [`nextmail.settings.get()`](https://nextmail.sh/docs/sdk/reference/settings#get); Python [`settings.get()`](https://nextmail.sh/docs/python/reference/settings#get); Ruby [`settings.get`](https://nextmail.sh/docs/ruby/reference/settings#get); PHP [`settings->get`](https://nextmail.sh/docs/php/reference/settings#get); Go [`Settings.Get`](https://nextmail.sh/docs/go/reference/settings#get); Java [`settings().get`](https://nextmail.sh/docs/java/reference/settings#get); C# [`Settings.GetAsync`](https://nextmail.sh/docs/csharp/reference/settings#get). ### `updateSettings` 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. - Scopes: `settings:write`. - The app's assistant asks first unless you asked for it. - Toolkit: `workspace`. **Inputs** - `address` (`string`, 3 to 320 characters): One address, such as hello@example.com, *@example.com for the catch-all of a domain, or @example.com for a whole domain. - `values` (`Record`, required): The settings to change, by the names getSettings reports, such as { "timezone": "Europe/Berlin" } or { "signature": "

Best, Ada

" }. null removes a value the scope sets itself, so it inherits again: { "externalImages": null } with an address goes back to the domain's or the workspace's choice. Also available in: API [`PATCH /settings`](https://nextmail.sh/docs/api/reference/settings#patch-settings); TypeScript [`nextmail.settings.update()`](https://nextmail.sh/docs/sdk/reference/settings#update); Python [`settings.update()`](https://nextmail.sh/docs/python/reference/settings#update); Ruby [`settings.update`](https://nextmail.sh/docs/ruby/reference/settings#update); PHP [`settings->update`](https://nextmail.sh/docs/php/reference/settings#update); Go [`Settings.Update`](https://nextmail.sh/docs/go/reference/settings#update); Java [`settings().update`](https://nextmail.sh/docs/java/reference/settings#update); C# [`Settings.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/settings#update). ### `getOutOfOffice` 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. - Scopes: `settings:read`. - The app's assistant runs it without asking. - Toolkit: `core`. **Inputs** - `address` (`string`, 3 to 320 characters): One address, such as hello@example.com, or *@example.com for the catch-all of a domain. Also available in: API [`GET /out-of-office`](https://nextmail.sh/docs/api/reference/settings#get-out-of-office); TypeScript [`nextmail.outOfOffice.list()`](https://nextmail.sh/docs/sdk/reference/out-of-office#list); Python [`out_of_office.list()`](https://nextmail.sh/docs/python/reference/out-of-office#list); Ruby [`out_of_office.list`](https://nextmail.sh/docs/ruby/reference/out-of-office#list); PHP [`outOfOffice->list`](https://nextmail.sh/docs/php/reference/out-of-office#list); Go [`OutOfOffice.List`](https://nextmail.sh/docs/go/reference/out-of-office#list); Java [`outOfOffice().list`](https://nextmail.sh/docs/java/reference/out-of-office#list); C# [`OutOfOffice.ListAsync`](https://nextmail.sh/docs/csharp/reference/out-of-office#list). ### `setOutOfOffice` 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. - Scopes: `settings:write`. - The app's assistant asks first unless you asked for it. - Toolkit: `core`. **Inputs** - `address` (`string`, required, 3 to 320 characters): One address, such as hello@example.com, or *@example.com for the catch-all of a domain. - `enabled` (`boolean`, default `true`) - `startsAt` (`string`, nullable, format `date-time`) - `endsAt` (`string`, nullable, format `date-time`) - `subject` (`string`, up to 255 characters, default `""`) - `message` (`string`, required, 1 to 10000 characters) - `contactsOnly` (`boolean`, default `false`) Also available in: API [`PUT /out-of-office`](https://nextmail.sh/docs/api/reference/settings#put-out-of-office); TypeScript [`nextmail.outOfOffice.set()`](https://nextmail.sh/docs/sdk/reference/out-of-office#set); Python [`out_of_office.set()`](https://nextmail.sh/docs/python/reference/out-of-office#set); Ruby [`out_of_office.set`](https://nextmail.sh/docs/ruby/reference/out-of-office#set); PHP [`outOfOffice->set`](https://nextmail.sh/docs/php/reference/out-of-office#set); Go [`OutOfOffice.Set`](https://nextmail.sh/docs/go/reference/out-of-office#set); Java [`outOfOffice().set`](https://nextmail.sh/docs/java/reference/out-of-office#set); C# [`OutOfOffice.SetAsync`](https://nextmail.sh/docs/csharp/reference/out-of-office#set). ### `clearOutOfOffice` 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. - Scopes: `settings:write`. - The app's assistant asks first unless you asked for it. - Toolkit: `core`. **Inputs** - `address` (`string`, required, 3 to 320 characters): One address, such as hello@example.com, or *@example.com for the catch-all of a domain. Also available in: API [`DELETE /out-of-office`](https://nextmail.sh/docs/api/reference/settings#delete-out-of-office); TypeScript [`nextmail.outOfOffice.clear()`](https://nextmail.sh/docs/sdk/reference/out-of-office#clear); Python [`out_of_office.clear()`](https://nextmail.sh/docs/python/reference/out-of-office#clear); Ruby [`out_of_office.clear`](https://nextmail.sh/docs/ruby/reference/out-of-office#clear); PHP [`outOfOffice->clear`](https://nextmail.sh/docs/php/reference/out-of-office#clear); Go [`OutOfOffice.Clear`](https://nextmail.sh/docs/go/reference/out-of-office#clear); Java [`outOfOffice().clear`](https://nextmail.sh/docs/java/reference/out-of-office#clear); C# [`OutOfOffice.ClearAsync`](https://nextmail.sh/docs/csharp/reference/out-of-office#clear). ### `listSignatures` 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. - Scopes: `settings:read`. - The app's assistant runs it without asking. - Toolkit: `workspace`. **Inputs** - `address` (`string`, 3 to 320 characters): One address, such as hello@example.com, or *@example.com for the catch-all of a domain. - `limit` (`integer`, at least 1, at most 100) - `cursor` (`string`) Also available in: API [`GET /signatures`](https://nextmail.sh/docs/api/reference/settings#get-signatures), [`GET /signatures/{id}`](https://nextmail.sh/docs/api/reference/settings#get-signatures-id); TypeScript [`nextmail.signatures.list()`](https://nextmail.sh/docs/sdk/reference/signatures#list), [`nextmail.signatures.listAll()`](https://nextmail.sh/docs/sdk/reference/signatures#listAll), [`nextmail.signatures.iterate()`](https://nextmail.sh/docs/sdk/reference/signatures#iterate), [`nextmail.signatures.get()`](https://nextmail.sh/docs/sdk/reference/signatures#get); Python [`signatures.list()`](https://nextmail.sh/docs/python/reference/signatures#list), [`signatures.list_all()`](https://nextmail.sh/docs/python/reference/signatures#listAll), [`signatures.iterate()`](https://nextmail.sh/docs/python/reference/signatures#iterate), [`signatures.get()`](https://nextmail.sh/docs/python/reference/signatures#get); Ruby [`signatures.list`](https://nextmail.sh/docs/ruby/reference/signatures#list), [`signatures.list_all`](https://nextmail.sh/docs/ruby/reference/signatures#listAll), [`signatures.iterate`](https://nextmail.sh/docs/ruby/reference/signatures#iterate), [`signatures.get`](https://nextmail.sh/docs/ruby/reference/signatures#get); PHP [`signatures->list`](https://nextmail.sh/docs/php/reference/signatures#list), [`signatures->listAll`](https://nextmail.sh/docs/php/reference/signatures#listAll), [`signatures->iterate`](https://nextmail.sh/docs/php/reference/signatures#iterate), [`signatures->get`](https://nextmail.sh/docs/php/reference/signatures#get); Go [`Signatures.List`](https://nextmail.sh/docs/go/reference/signatures#list), [`Signatures.ListAll`](https://nextmail.sh/docs/go/reference/signatures#listAll), [`Signatures.Iterate`](https://nextmail.sh/docs/go/reference/signatures#iterate), [`Signatures.Get`](https://nextmail.sh/docs/go/reference/signatures#get); Java [`signatures().list`](https://nextmail.sh/docs/java/reference/signatures#list), [`signatures().listAll`](https://nextmail.sh/docs/java/reference/signatures#listAll), [`signatures().iterate`](https://nextmail.sh/docs/java/reference/signatures#iterate), [`signatures().get`](https://nextmail.sh/docs/java/reference/signatures#get); C# [`Signatures.ListAsync`](https://nextmail.sh/docs/csharp/reference/signatures#list), [`Signatures.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/signatures#listAll), [`Signatures.IterateAsync`](https://nextmail.sh/docs/csharp/reference/signatures#iterate), [`Signatures.GetAsync`](https://nextmail.sh/docs/csharp/reference/signatures#get). ### `createSignature` Add a signature to one address, or to a catch-all with *@domain. html is the signature as HTML, such as

Ada Lovelace
Acme Ltd

, 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. - Scopes: `settings:write`. - The app's assistant asks first unless you asked for it. - Toolkit: `workspace`. **Inputs** - `address` (`string`, required, 3 to 320 characters): The address the signature is for, such as hello@example.com, or *@example.com for the catch-all of a domain. - `name` (`string`, required, 1 to 80 characters): What the signature is called. Unique on its address, whatever the case. - `html` (`string`, required, 1 to 150000 characters): The signature as HTML. It is sanitised on write and has to keep some text or an image. - `isDefault` (`boolean`): true makes it the signature of new mail from the address. false takes that away when it held it. - `isReplyDefault` (`boolean`): true makes it the signature of replies and forwards from the address. false takes that away when it held it. Also available in: API [`POST /signatures`](https://nextmail.sh/docs/api/reference/settings#post-signatures); TypeScript [`nextmail.signatures.create()`](https://nextmail.sh/docs/sdk/reference/signatures#create); Python [`signatures.create()`](https://nextmail.sh/docs/python/reference/signatures#create); Ruby [`signatures.create`](https://nextmail.sh/docs/ruby/reference/signatures#create); PHP [`signatures->create`](https://nextmail.sh/docs/php/reference/signatures#create); Go [`Signatures.Create`](https://nextmail.sh/docs/go/reference/signatures#create); Java [`signatures().create`](https://nextmail.sh/docs/java/reference/signatures#create); C# [`Signatures.CreateAsync`](https://nextmail.sh/docs/csharp/reference/signatures#create). ### `updateSignature` 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. - Scopes: `settings:write`. - The app's assistant asks first unless you asked for it. - Toolkit: `workspace`. **Inputs** - `id` (`string`, required, 1 to 64 characters): The id of the signature, as listSignatures reports it. - `name` (`string`, 1 to 80 characters): What the signature is called. Unique on its address, whatever the case. - `html` (`string`, 1 to 150000 characters): The signature as HTML. It is sanitised on write and has to keep some text or an image. - `isDefault` (`boolean`): true makes it the signature of new mail from the address. false takes that away when it held it. - `isReplyDefault` (`boolean`): true makes it the signature of replies and forwards from the address. false takes that away when it held it. Also available in: API [`PATCH /signatures/{id}`](https://nextmail.sh/docs/api/reference/settings#patch-signatures-id); TypeScript [`nextmail.signatures.update()`](https://nextmail.sh/docs/sdk/reference/signatures#update); Python [`signatures.update()`](https://nextmail.sh/docs/python/reference/signatures#update); Ruby [`signatures.update`](https://nextmail.sh/docs/ruby/reference/signatures#update); PHP [`signatures->update`](https://nextmail.sh/docs/php/reference/signatures#update); Go [`Signatures.Update`](https://nextmail.sh/docs/go/reference/signatures#update); Java [`signatures().update`](https://nextmail.sh/docs/java/reference/signatures#update); C# [`Signatures.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/signatures#update). ### `deleteSignature` 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. - Scopes: `settings:write`. - The app's assistant always asks first. - Toolkit: `workspace`. **Inputs** - `id` (`string`, required, 1 to 64 characters): The id of the signature, as listSignatures reports it. Also available in: API [`DELETE /signatures/{id}`](https://nextmail.sh/docs/api/reference/settings#delete-signatures-id); TypeScript [`nextmail.signatures.delete()`](https://nextmail.sh/docs/sdk/reference/signatures#delete); Python [`signatures.delete()`](https://nextmail.sh/docs/python/reference/signatures#delete); Ruby [`signatures.delete`](https://nextmail.sh/docs/ruby/reference/signatures#delete); PHP [`signatures->delete`](https://nextmail.sh/docs/php/reference/signatures#delete); Go [`Signatures.Delete`](https://nextmail.sh/docs/go/reference/signatures#delete); Java [`signatures().delete`](https://nextmail.sh/docs/java/reference/signatures#delete); C# [`Signatures.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/signatures#delete). ### `copySignature` 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. - Scopes: `settings:write`. - The app's assistant asks first unless you asked for it. - Toolkit: `workspace`. **Inputs** - `id` (`string`, required, 1 to 64 characters): The id of the signature, as listSignatures reports it. - `addresses` (`string[]`, required, 1 to 500 items): The addresses to copy it to. Each is one address or *@example.com for a catch-all. - `isDefault` (`boolean`): true makes it the signature of new mail from the address. false takes that away when it held it. - `isReplyDefault` (`boolean`): true makes it the signature of replies and forwards from the address. false takes that away when it held it. Also available in: API [`POST /signatures/{id}/copy`](https://nextmail.sh/docs/api/reference/settings#post-signatures-id-copy); TypeScript [`nextmail.signatures.copy()`](https://nextmail.sh/docs/sdk/reference/signatures#copy); Python [`signatures.copy()`](https://nextmail.sh/docs/python/reference/signatures#copy); Ruby [`signatures.copy`](https://nextmail.sh/docs/ruby/reference/signatures#copy); PHP [`signatures->copy`](https://nextmail.sh/docs/php/reference/signatures#copy); Go [`Signatures.Copy`](https://nextmail.sh/docs/go/reference/signatures#copy); Java [`signatures().copy`](https://nextmail.sh/docs/java/reference/signatures#copy); C# [`Signatures.CopyAsync`](https://nextmail.sh/docs/csharp/reference/signatures#copy). ### `listWorkspaceSecurityEvents` 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. - Scopes: `members:read`. - The app's assistant runs it without asking. - Toolkit: `workspace`. **Inputs** - `limit` (`integer`, at least 1, at most 100): How many entries to return, newest first. 50 when left out. - `cursor` (`string`, not empty): The cursor the previous page ended with, to read the entries before it. Also available in: API [`GET /security/events`](https://nextmail.sh/docs/api/reference/security#get-security-events); TypeScript [`nextmail.security.listEvents()`](https://nextmail.sh/docs/sdk/reference/security#listEvents), [`nextmail.security.listAllEvents()`](https://nextmail.sh/docs/sdk/reference/security#listAllEvents), [`nextmail.security.iterateEvents()`](https://nextmail.sh/docs/sdk/reference/security#iterateEvents); Python [`security.list_events()`](https://nextmail.sh/docs/python/reference/security#listEvents), [`security.list_all_events()`](https://nextmail.sh/docs/python/reference/security#listAllEvents), [`security.iterate_events()`](https://nextmail.sh/docs/python/reference/security#iterateEvents); Ruby [`security.list_events`](https://nextmail.sh/docs/ruby/reference/security#listEvents), [`security.list_all_events`](https://nextmail.sh/docs/ruby/reference/security#listAllEvents), [`security.iterate_events`](https://nextmail.sh/docs/ruby/reference/security#iterateEvents); PHP [`security->listEvents`](https://nextmail.sh/docs/php/reference/security#listEvents), [`security->listAllEvents`](https://nextmail.sh/docs/php/reference/security#listAllEvents), [`security->iterateEvents`](https://nextmail.sh/docs/php/reference/security#iterateEvents); Go [`Security.ListEvents`](https://nextmail.sh/docs/go/reference/security#listEvents), [`Security.ListAllEvents`](https://nextmail.sh/docs/go/reference/security#listAllEvents), [`Security.IterateEvents`](https://nextmail.sh/docs/go/reference/security#iterateEvents); Java [`security().listEvents`](https://nextmail.sh/docs/java/reference/security#listEvents), [`security().listAllEvents`](https://nextmail.sh/docs/java/reference/security#listAllEvents), [`security().iterateEvents`](https://nextmail.sh/docs/java/reference/security#iterateEvents); C# [`Security.ListEventsAsync`](https://nextmail.sh/docs/csharp/reference/security#listEvents), [`Security.ListAllEventsAsync`](https://nextmail.sh/docs/csharp/reference/security#listAllEvents), [`Security.IterateEventsAsync`](https://nextmail.sh/docs/csharp/reference/security#iterateEvents).