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.

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.

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

Every new Agent Account goes through a three-step decision to find its workspace:

Explicit assignment — if you pass a workspace_id in the POST /v3/connect/custom payload, the grant joins that workspace immediately.
Domain auto-group — if no workspace_id is given, Nylas checks whether a custom workspace exists whose domain matches the grant’s email domain and whose auto_group is true. If one matches, the grant joins it.
Default workspace — if neither condition above applies, the grant lands in the application’s default workspace.

To move a grant after it has been created, use PATCH /v3/grants/{grant_id} with a new workspace_id, or use the manual-assign endpoint to reassign up to 500 grants at a time.

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.

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 sort existing grants in bulk by domain, use the Automatically Group Grants endpoint, which runs a background job and creates domain workspaces as needed.

The default workspace

Every application has exactly one default workspace that Nylas creates automatically when the application is provisioned. The application object exposes its ID as default_workspace_id (a UUID string). Any grant that isn’t explicitly assigned or domain auto-grouped lands here.

The default workspace is protected. You can update only policy_id and rule_ids on it — name, domain, and auto_group are locked and return an error if you try to change them. You can’t delete the default workspace.

Manage policy and rules on a workspace

Both default and non-default workspaces can have a policy and rules assigned, updated, or removed. Use PATCH /v3/workspaces/{workspace_id} and include only the fields you want to change:

Omit a field — no change to the current value.
Set a field to a value — overwrites the current value. policy_id takes a single UUID string; rule_ids takes an array of UUID strings.
Set a field to null — clears the value. Setting policy_id: null detaches the policy; setting rule_ids: null removes all rules.

A workspace with no policy_id runs its accounts at your billing plan’s maximum limits. Attaching a policy narrows those limits to whatever the policy defines.

Things to know about workspaces

	Default workspace	Non-default workspace
`domain`	Locked	Locked after creation
`name`	Locked	Updatable
`auto_group`	Locked	Updatable
`policy_id`	Updatable (single UUID or `null`)	Updatable (single UUID or `null`)
`rule_ids`	Updatable (UUID array or `null`)	Updatable (UUID array or `null`)
Delete	Not allowed	Allowed

Manual assignment via POST /v3/workspaces/{workspace_id}/manual-assign works only when the workspace’s auto_group is false.

Plan your workspace structure early. A workspace’s domain can’t change after creation, so decide which domains map to which workspaces before you start provisioning accounts. Use one workspace per agent archetype — a sales-outreach group and a support-triage group have different send limits and spam tolerances.

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