Default Workspaces and Where New Agents Land

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 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. The placement algorithm When a new account is created, placement resolves in this order: Explicit workspace_id on the request — the account goes exactly where you said. The target workspace must belong to the same application; ownership is validated and mismatches are rejected. Auto-grouping by domain — if a workspace has auto_group enabled and its domain matches the new account's email domain, the account joins it automatically. The default workspace — everything else lands here. That third bucket is the interesting one. What the default workspace actually is 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