Workspaces: Policy Management for Fleets of Agents

One policy object can govern every agent mailbox you'll ever create. That's the design decision at the center of Agent Accounts governance: you don't configure limits, spam settings, or mail rules on individual accounts at all. You attach them to a workspace, and every account in that workspace inherits the lot — which changes fleet security from a per-account chore into a single point of control.

The inheritance chain

Agent Accounts (currently in beta) are hosted mailboxes for AI agents and system identities, and their guardrails come from three application-scoped resources described in Policies, Rules, and Lists:

• Policies bundle limits (send quotas, storage, attachments, retention) and spam detection settings.
• Rules match inbound mail or outbound sends and run actions like block, mark_as_spam, or assign_to_folder.
• Lists are typed collections of domains, TLDs, or addresses that rules reference through the in_list operator.

None of them attach to a grant directly. A workspace carries one policy_id plus an array of rule_ids, and each Agent Account carries a workspace_id. When mail arrives, the grant's workspace is resolved, the policy's limits and spam settings apply, and the workspace's inbound rules run in priority order. When the account sends, the same workspace's outbound rules are evaluated first. One array holds both directions; filtering by each rule's trigger happens at evaluation time, so an outbound rule never runs on received mail.

The security consequence is multiplied control. Need to block a newly discovered bad domain across 500 agents? Update one list. Need tighter attachment limits fleet-wide? Patch one policy. No redeploys, no fan-out script touching every grant.

Wiring a workspace up is one request — name it, optionally bind it to a domain, and reference the policy and rules it should carry:

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

Changing governance later is a PATCH /v3/workspaces/{workspace_id} with a new policy_id or rule_ids array — every account in the workspace picks up the change without being touched individually.

The default workspace catches strays

Every application gets one default workspace, created and managed for you. Any Agent Account created without an explicit workspace_id — and not auto-grouped by domain — lands there. That makes the default workspace your safety net: attach a baseline policy and rule set to it, and there's no such thing as an ungoverned account in your application.

This matters more than it sounds. Fleet incidents often start with the account someone provisioned in a hurry and forgot to configure. With a policied default workspace, the forgotten account still inherits your baseline. One constraint to know: on the default workspace, policy_id and rule_ids are the only fields you can update — the rest is managed for you.

Be aware of the unconfigured case too: a workspace with no policy_id runs its accounts at your billing plan's maximum limits. That's fine for a sandbox, probably not what you want for production.

Placement: explicit, automatic, or default

You control where an account lands at creation time by passing a top-level workspace_id:

curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header "Authorization: Bearer $NYLAS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "nylas",
    "workspace_id": "<WORKSPACE_ID>",
    "settings": {
      "email": "[e-mail]"
    }
  }'

There's a hands-off option as well: a workspace with auto_group: true automatically claims new accounts whose email domain matches the workspace's domain. If your domains already encode meaning — staging versus production, customer A versus customer B — placement becomes a side effect of the address.

Moving an existing account is a PATCH /v3/grants/{grant_id} with a new workspace_id. The target workspace must belong to the same application; ownership is validated and cross-application moves are rejected.

Designing workspaces for a fleet

The docs' recommendation is one workspace per agent archetype, and it's the right mental model. A sales-outreach agent and a support-triage agent have different send limits and spam tolerances — give each class its own workspace and policy instead of one catch-all. A reasonable starting taxonomy:

• Production outreach — strict outbound rules, send quotas sized to the campaign.
• Production support — aggressive inbound filtering, modest send limits.
• Prototypes and CI — tight everything, short retention.

When you build the rules behind those workspaces, the caps are generous enough that you rarely think about them, but they exist: up to 50 conditions and 20 actions per rule, 10 lists per in_list condition, 500 characters per condition value, and 1,000 items per list-addition request. Auditing is built in too — GET /v3/grants/{grant_id}/rule-evaluations shows which rules fired for any account, so "why was this message blocked?" has a queryable answer.

You can inspect current state from the CLI with nylas agent policy list and nylas agent rule list; creation and updates go through the API.

Things to watch for

A few behaviors that surprise teams the first time a workspace policy fires in production:

• Outbound blocks return 403 to the sender, and they're final. No sent copy is stored and no retry will deliver the message. Your agent's send wrapper should treat it as a permanent failure and consult the rule-evaluations endpoint for the matching rule.
• Rule evaluation fails closed. If a block rule can't be evaluated because of a transient infrastructure error — a list lookup failing mid-in_list, say — the message is blocked rather than let through. These surface as retryable errors (503 on an API send, a 451 SMTP tempfail inbound) and the audit record carries blocked_by_evaluation_error: true, so you can tell an infrastructure hiccup from a genuine match.
• Inbound and outbound see different fields. Inbound rules match only from.address, from.domain, and from.tld. Outbound rules add recipient.* (which matches To, CC, BCC, and envelope recipients) and outbound.type (compose or reply). Don't try to filter sends with an inbound rule — the directions are isolated on purpose.
• Non-blocking outbound actions touch only the sent copy. archive, mark_as_read, and friends organize what's stored in the agent's sent folder; they never change what the recipient receives.
• Retention values have an ordering constraint. limit_spam_retention_period must be shorter than limit_inbox_retention_period, so spam ages out ahead of real mail. The free-plan defaults are 30 days for the inbox and 7 for spam.

Start with two workspaces

If your agents currently all live wherever they landed, the first move is small: attach a baseline policy to the default workspace, then create one custom workspace for your highest-risk agent class and move those accounts into it. That's three API calls, and it converts your fleet from individually configured (or unconfigured) accounts into governed groups. Which of your agents would end up in the strict workspace first?