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 " \ --header "Content-Type: application/json" \ --data '{ "provider": "nylas", "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 itsdomain 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 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. What inheritance buys you 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 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. Moving an account after the fact 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/ " \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "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. Checking what an account actually inherited 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/ /rule-evaluations?limit=50" \ --header "Authorization: Bearer " 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. A sane starting configuration If you're setting this up fresh (the quickstart gets you a working account in under 5 minutes), here's the order that avoids surprises: - Create a baseline policy with conservative limits: curl --request POST \ --url "https://api.us.nylas.com/v3/policies" \ --header "Authorization: Bearer " \ --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. - Attach it to the default workspace ( PATCH withpolicy_id ) so strays are covered. - Create one workspace per agent type, each with its own policy and rules. Enable auto_group with adomain if your agent types map cleanly to domains. - Pass 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? Top comments (0)