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.
When a new account is created, placement resolves in this order:
workspace_id
on the requestauto_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 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 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?