How Agent Account workspaces work

A workspace groups the Agent Accounts in your application by a shared attribute, usually their email domain, and carries the policy and rules that govern every account inside it. Instead of setting limits and mail filtering on each grant one at a time, you configure them once on the workspace and every member inherits them. This page covers how workspaces work, how to create one, and how accounts get assigned.

New to Agent Accounts? Start with the Agent Accounts quickstart to provision your first account, then come back to organize accounts into workspaces.

What is a workspace?

A workspace is a container that groups Agent Accounts and holds one policy_id plus an array of rule_ids. Every account in the workspace inherits that policy’s limits and spam settings, and runs the workspace’s rules on its mail. The policy sets send caps (for example, 200 messages per account per day on the free plan), storage, and retention.

The pieces form a chain. A policy bundles limits and spam detection, rules describe match conditions and actions, and a workspace references one policy and a list of rules. A grant carries a workspace_id that points at its workspace, so changing the workspace’s policy reconfigures every account in it at once.

Create a workspace

Create a workspace with a POST /v3/workspaces request. You can set 5 fields: name, domain, auto_group, policy_id, and rule_ids. The domain ties the workspace to one email domain, and auto_group controls whether matching accounts join it automatically. The response returns the workspace_id you store on grants.

Request

curl --request POST \
  --url "https://api.us.nylas.com/v3/workspaces" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "The Nylas Workspace",
    "domain": "nylas.com",
    "auto_group": true,
    "policy_id": "<POLICY_ID>",
    "rule_ids": ["<RULE_ID>"]
  }'

A workspace with no policy_id runs its accounts at your billing plan’s maximum limits, so you can create the grouping first and attach a policy later. To attach or change the policy, see Attach a policy to a workspace.

Assign Agent Accounts to a workspace

An Agent Account joins a workspace one of three ways: you pass a workspace_id when you create the grant, the account is auto-grouped by domain when auto_group is true, or you assign it manually after the fact. Manual assignment moves up to 500 grants per request across 2 fields, assign_grants and remove_grants.

The Update Workspace Assignments endpoint, POST /v3/workspaces/{workspace_id}/manual-assign, adds or removes specific grants from a workspace whose auto_group is false. Send grant IDs in assign_grants, remove_grants, or both, with up to 500 IDs per list.

Request

curl --request POST \
  --url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>/manual-assign" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "assign_grants": [
      "10726e7c-89c3-4a1d-9f4a-5f3f37f6f2d9",
      "3b9f5c1a-21d4-46c1-b84f-0e8d1f9eaa42"
    ],
    "remove_grants": [
      "5f1a2c9e-739b-4c66-9a3d-2c88a0c6d123",
      "9c6e4b7d-2e4a-4ef0-a1b8-badf5a76a555"
    ]
  }'

To set a workspace at creation time, pass workspace_id on POST /v3/connect/custom. To sort existing grants in bulk by domain, use the Automatically Group Grants endpoint, which runs a background job and creates new domain workspaces when needed.

The default workspace

Every application has exactly 1 default workspace that Nylas creates and manages automatically. Any Agent Account created without a workspace_id, and not auto-grouped by domain, lands here. The application object exposes its ID as default_workspace_id. You can update only 2 fields on it, policy_id and rule_ids, and you can’t delete it.

Attach your policy and rules to the default workspace to cover every unassigned account in one place. Applications created before default workspaces existed might not have one, so check for default_workspace_id on the application before you rely on it.

Things to know about workspaces

A few constraints shape how you design your grouping. A workspace’s domain is fixed at creation and can’t change afterward, on any workspace. The default workspace is protected: renaming it, toggling its auto_group, or deleting it returns an error, and you can update just 2 fields on it. Manual assignment works only when a workspace’s auto_group is false.

These constraints favor a clear plan up front. Use one workspace per agent archetype (a sales-outreach group and a support-triage group have different send limits and spam tolerances), set each workspace’s domain when you create it, and decide early whether accounts join by domain matching or by explicit assignment.

What’s next

• Policies, Rules, and Lists to configure the limits and rules a workspace carries
• Provisioning Agent Accounts to create accounts and set their workspace_id
• Workspaces API reference for the full endpoint set, including auto-group and manual-assign