Workspaces

Workspaces group and organize grants in a Nylas application. A workspace can group grants by email domain (for example, nylas.com), or it can have no domain and hold whichever grants you assign to it. For how grants are assigned to workspaces, what the default workspace does, and how to move and filter grants, see How workspaces group grants.

Assign grants to workspaces

Nylas offers two endpoints to manage the grants a workspace contains:

• Automatically Group Grants into Workspaces: Starts a background job that, based on your filters, processes existing grants in your application and automatically sorts them to existing workspaces. If necessary, Nylas automatically creates new workspaces.
• Update Workspace Assignments: Manually specify a workspace ID and up to 500 grants to add or remove from that workspace.

You can also move a single grant by passing a new workspace_id to the Update Grant endpoint.

Default workspace

An application can have a default workspace, which Nylas creates automatically when the application is created and manages on your behalf. Applications created before default workspaces were introduced might not have one. When you retrieve workspaces, Nylas identifies the default workspace with "default": true, and the application object exposes its ID as default_workspace_id.

The default workspace is protected: you can update only its policy_id and rule_ids values (changes to name or auto_group return an error), and you can't delete it.

Policies and rules

Workspaces can carry a policy (policy_id) and rules (rule_ids). Agent Accounts in a workspace use the policy attached to the workspace for limits and spam settings, and the rules attached to the workspace for mail filtering. These fields have no effect on grants from other providers.

Workspace limitations

• domain is optional. It's only used for automatic grouping. Domain matching is an exact, case-sensitive comparison, and each domain can belong to only one workspace per application. You can't add, change, or remove a workspace's domain after you create it.
• auto_group defaults to false. When it's false, Nylas doesn't automatically assign new grants to the workspace. Add grants to it with the Update Workspace Assignments endpoint or by passing its ID as the workspace_id in an Update Grant request.
• When auto_group is true, Nylas automatically assigns new grants with a matching email domain to the workspace. You can still assign grants to an auto_group workspace manually, and later automatic grouping jobs don't move grants you placed manually. Automatic grouping needs a domain, so you can't enable auto_group on a workspace without one.
• Manual assignment doesn't check email domains. You can assign any grant in the application to any workspace, including grants from other domains and grants without an email address.
• Removing a grant from a workspace with remove_grants clears the grant's workspace_id. You can't clear it with the Update Grant endpoint. The grant isn't returned to the default workspace until you assign it somewhere or an automatic grouping job picks it up.