Default Workspaces and Where New Agents Land

Nylas has detailed how its Agent Accounts land in workspaces, with a default workspace acting as a safety net for unplaced accounts. The workspace carries policy limits and rules that govern agents, and placement can be updated via a single grant PATCH request. The company recommends attaching a conservative baseline policy to the default workspace to ensure unassigned accounts have sane guardrails.

Every Agent Account you create lands in a workspace — the only question is whether you picked it or the platform did: 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": "test@your-application.nylas.email" } }' That top-level workspace id is optional, and what happens when you omit it is one of the more under-read parts of the Nylas Agent Accounts https://developer.nylas.com/docs/v3/agent-accounts/policies-rules-lists/ docs the feature's in beta, so read with that in mind . Workspaces aren't cosmetic grouping — they're the carrier for every policy limit and mail rule that governs your agents. Getting placement wrong means an agent running with the wrong send quota, the wrong spam settings, or no inbound filtering at all. When a new account is created, placement resolves in this order: workspace id on the request auto group enabled and its domain matches the new account's email domain, the account joins it automatically.That third bucket is the interesting one. Every application gets exactly one default workspace, created and managed by the platform. You can't delete it, and you can only update two of its fields: policy id and rule ids . Everything else is managed for you. It's easy to read "default" as "throwaway," but it's better understood as your safety net. Any account you forget to place explicitly — a quick test from the CLI, a provisioning script missing the workspace parameter — inherits whatever the default workspace carries. Which leads to a practical recommendation: attach a conservative baseline policy and your spam-blocking rules to the default workspace on day one. Then unassigned accounts get sane guardrails instead of running wide open. Because that's the alternative: a workspace with no policy id runs its accounts at your billing plan's maximum limits. No custom send quota, no retention tightening, no spam-sensitivity tuning. Fine for a sandbox; probably not what you want for whatever an intern provisions on a Friday. A workspace carries one policy id plus an array of rule ids , and every account inside inherits both. The policy bundles limits attachment size and count, storage, daily send quotas, inbox and spam retention and spam detection DNSBL checks, header anomaly detection, and a spam sensitivity dial that runs from 0.1 to 5.0 . The rules array carries both inbound and outbound rules together — the engine filters by trigger at evaluation time, and rules run in priority order from 0 to 1000, lowest first, with 10 as the default. The payoff is that none of this configuration lives on individual grants. Update the workspace's policy and every account in it picks up the change. The docs https://developer.nylas.com/docs/v3/agent-accounts/policies-rules-lists/ suggest one workspace per agent archetype — your sales-outreach agents and your support-triage agents want different send limits and spam tolerances, so give each group its own workspace rather than one catch-all. Placement isn't permanent. An account that landed in the default workspace can be moved with a single grant update: curl --request PATCH \ --url "https://api.us.nylas.com/v3/grants/<NYLAS GRANT ID " \ --header "Authorization: Bearer <NYLAS API KEY " \ --header "Content-Type: application/json" \ --data '{ "workspace id": "<WORKSPACE ID " }' From that point the account picks up the new workspace's policy and rules. This makes a "graduate the agent" workflow trivial: prototype in the default workspace, then PATCH it into the production workspace — with its stricter outbound rules and tuned spam sensitivity — when it's ready. Inheritance is invisible until something gets blocked or routed, so the platform keeps receipts. Every rule evaluation — inbound message, SMTP envelope, or outbound send — writes an audit record you can read per grant: curl --request GET \ --url "https://api.us.nylas.com/v3/grants/<NYLAS GRANT ID /rule-evaluations?limit=50" \ --header "Authorization: Bearer <NYLAS API KEY " Each record names the evaluation stage smtp rcpt for messages rejected before acceptance, inbox processing for post-acceptance evaluation, outbound send for send-time checks , the matched rule IDs, and the actions applied. If an account is sitting in the wrong workspace, this endpoint is usually where you find out — the rules you expected to match never show up in matched rule ids . One subtlety worth internalizing: rule evaluation fails closed. If a block rule can't be evaluated because of a transient infrastructure error, the message is blocked rather than let through — surfaced as a retryable 503 on sends or an SMTP 451 tempfail inbound, with blocked by evaluation error: true on the audit record so you can tell an outage from a genuine match. If you're setting this up fresh the quickstart https://developer.nylas.com/docs/v3/getting-started/agent-accounts/ gets you a working account in under 5 minutes , here's the order that avoids surprises: curl --request POST \ --url "https://api.us.nylas.com/v3/policies" \ --header "Authorization: Bearer <NYLAS API KEY " \ --header "Content-Type: application/json" \ --data '{ "name": "Baseline Agent Policy", "limits": { "limit attachment size limit": 26214400, "limit attachment count limit": 20, "limit inbox retention period": 365, "limit spam retention period": 30 }, "spam detection": { "use list dnsbl": true, "use header anomaly detection": true, "spam sensitivity": 1.0 } }' Every limit is optional — omit one and it defaults to your plan's maximum, while a value above the plan maximum is rejected with an error. Two tuning notes from the docs: start spam sensitivity at 1.0 and adjust from observed behavior, and keep limit spam retention period shorter than limit inbox retention period so spam clears out ahead of the inbox. PATCH with policy id so strays are covered. auto group with a domain if your agent types map cleanly to domains. workspace id explicitly in your provisioning code anyway — auto-grouping is a backstop, not a substitute for being intentional.The whole model rewards thinking about workspaces before you scale account creation, because retrofitting placement across hundreds of grants means a hundred PATCH calls. Next step: list your current grants, check which workspace each actually sits in, and ask whether the default workspace has a policy attached. If the answer is "no policy," your unassigned agents are running at plan maximums right now — is that what you intended?