{"slug": "default-workspaces-and-where-new-agents-land", "title": "Default Workspaces and Where New Agents Land", "summary": "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.", "body_md": "Every Agent Account you create lands in a workspace — the only question is whether you picked it or the platform did:\n\n```\ncurl --request POST \\\n --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n --header \"Authorization: Bearer \" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"provider\": \"nylas\",\n \"workspace_id\": \"\",\n \"settings\": {\n \"email\": \"test@your-application.nylas.email\"\n }\n }'\n```\n\nThat top-level `workspace_id`\n\nis 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.\n\nWhen a new account is created, placement resolves in this order:\n\n`workspace_id`\n\non the request`auto_group`\n\nenabled and its `domain`\n\nmatches the new account's email domain, the account joins it automatically.That third bucket is the interesting one.\n\nEvery 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`\n\nand `rule_ids`\n\n. Everything else is managed for you.\n\nIt'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.\n\nBecause that's the alternative: a workspace with no `policy_id`\n\nruns 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.\n\nA workspace carries one `policy_id`\n\nplus an array of `rule_ids`\n\n, 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`\n\ndial that runs from 0.1 to 5.0). The rules array carries both inbound and outbound rules together — the engine filters by `trigger`\n\nat evaluation time, and rules run in priority order from 0 to 1000, lowest first, with 10 as the default.\n\nThe 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.\n\nPlacement isn't permanent. An account that landed in the default workspace can be moved with a single grant update:\n\n```\ncurl --request PATCH \\\n --url \"https://api.us.nylas.com/v3/grants/\" \\\n --header \"Authorization: Bearer \" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"workspace_id\": \"\"\n }'\n```\n\nFrom 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`\n\nit into the production workspace — with its stricter outbound rules and tuned spam sensitivity — when it's ready.\n\nInheritance 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:\n\n```\ncurl --request GET \\\n --url \"https://api.us.nylas.com/v3/grants//rule-evaluations?limit=50\" \\\n --header \"Authorization: Bearer \"\n```\n\nEach record names the evaluation stage (`smtp_rcpt`\n\nfor messages rejected before acceptance, `inbox_processing`\n\nfor post-acceptance evaluation, `outbound_send`\n\nfor 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`\n\n.\n\nOne subtlety worth internalizing: rule evaluation fails closed. If a `block`\n\nrule can't be evaluated because of a transient infrastructure error, the message is blocked rather than let through — surfaced as a retryable `503`\n\non sends or an SMTP `451`\n\ntempfail inbound, with `blocked_by_evaluation_error: true`\n\non the audit record so you can tell an outage from a genuine match.\n\nIf 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:\n\n```\n curl --request POST \\\n --url \"https://api.us.nylas.com/v3/policies\" \\\n --header \"Authorization: Bearer \" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"name\": \"Baseline Agent Policy\",\n \"limits\": {\n \"limit_attachment_size_limit\": 26214400,\n \"limit_attachment_count_limit\": 20,\n \"limit_inbox_retention_period\": 365,\n \"limit_spam_retention_period\": 30\n },\n \"spam_detection\": {\n \"use_list_dnsbl\": true,\n \"use_header_anomaly_detection\": true,\n \"spam_sensitivity\": 1.0\n }\n }'\n```\n\nEvery 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`\n\nat 1.0 and adjust from observed behavior, and keep `limit_spam_retention_period`\n\nshorter than `limit_inbox_retention_period`\n\nso spam clears out ahead of the inbox.\n\n`PATCH`\n\nwith `policy_id`\n\n) so strays are covered.`auto_group`\n\nwith a `domain`\n\nif your agent types map cleanly to domains.`workspace_id`\n\nexplicitly 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`\n\ncalls.\n\nNext 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?", "url": "https://wpnews.pro/news/default-workspaces-and-where-new-agents-land", "canonical_source": "https://dev.to/qasim157/default-workspaces-and-where-new-agents-land-51g", "published_at": "2026-06-15 18:56:19+00:00", "updated_at": "2026-06-15 19:33:27.337587+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["Nylas", "Agent Accounts"], "alternates": {"html": "https://wpnews.pro/news/default-workspaces-and-where-new-agents-land", "markdown": "https://wpnews.pro/news/default-workspaces-and-where-new-agents-land.md", "text": "https://wpnews.pro/news/default-workspaces-and-where-new-agents-land.txt", "jsonld": "https://wpnews.pro/news/default-workspaces-and-where-new-agents-land.jsonld"}}