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 the policy and rules layer that workspaces add for Agent Accounts. For how workspaces group grants in general, including the default workspace, domain matching, and moving grants, see How workspaces group grants.

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

What does a workspace do for Agent Accounts?

For Agent Accounts, a workspace holds one policy_id plus an array of rule_ids, and every account in the workspace inherits both. The policy sets send caps (for example, 200 messages per account per day on the free plan), storage, retention, and spam detection. The rules run match conditions and actions against the account’s inbound and outbound mail.

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. Grants from Google, Microsoft, and the other providers can live in the same workspaces, but they ignore policy_id and rule_ids entirely.

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 optional domain ties the workspace to one email domain, and auto_group controls whether matching accounts join it automatically. Leave domain out to create a workspace that holds only the accounts you assign to it. 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

Agent Accounts are the only grant type you can place in a workspace at creation time. Pass a top-level workspace_id in the POST /v3/connect/custom payload and the account joins that workspace immediately, picking up its policy and rules before it sends its first message. If you omit workspace_id, the account follows the same 3-step resolution as every other grant: a domain match against a workspace with auto_group enabled, then the application’s default workspace.

To move an account after it has been created, pass a new workspace_id to PATCH /v3/grants/{grant_id}, or use the manual-assign endpoint to reassign up to 500 grants at a time. Both are described in Move grants between workspaces. The account starts using the new workspace’s policy and rules as soon as the move completes.

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. On the default workspace, policy_id and rule_ids are the only 2 fields you can change.

Things to know about Agent Account workspaces

Use one workspace per kind of agent. Agents that send outreach and agents that triage support mail need different send limits and spam settings, so give each group its own workspace and policy. If every Agent Account should share one baseline policy, attach it to the default workspace and create other workspaces only for exceptions.

A workspace’s domain can’t change after creation, and only one workspace per application can hold a given domain. Decide which domains map to which workspaces before you provision accounts. You can review the workspaces that hold Agent Accounts in the Nylas Dashboard.

What’s next

• How workspaces group grants for the default workspace, domain matching, and moving and filtering grants
• 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