Workspaces

Workspaces group and organize grants in a Nylas application by a common attribute, such as the email address domain (for example, nylas.com).

Assign grants to workspaces

Nylas offers two endpoints to manage workspaces and the grants they contain:

• Automatically Group Grants into Workspaces: Starts a background job that, based on your filters, processes existing grants in your Nylas 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.

Default workspace

A Nylas 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.

When a new grant is created without an explicit workspace_id, Nylas first tries to auto-group it into a workspace that has auto_group enabled and a domain that matches the grant's email address domain. If no domain workspace matches, Nylas assigns the grant to the application's default workspace, if one exists.

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. A workspace's domain can't be changed after creation, on any workspace.

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.

Workspace limitations

• Workspaces are designed to group grants by the top-level domain (TLD) of users' email addresses. Nylas allows you to manually assign grants to any workspace, but that workspace must have auto_group set to false.
• When auto_group is set to false, Nylas doesn't automatically assign grants to that workspace. You'll need to manually assign grants to the workspace using the Update Workspace Assignments endpoint.
• When auto_group is true, Nylas automatically assigns new grants to the workspace. You can move grants to a different workspace by making an Update Workspace Assignments request.