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": "[email protected]"

    }

  }'

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 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/<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.

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/<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.

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:

1. Create a baseline policy with conservative limits:
   

   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.

1. Attach it to the default workspace (PATCH with policy_id) so strays are covered.


2. Create one workspace per agent type, each with its own policy and rules. Enable auto_group with a domain if your agent types map cleanly to domains.


3. 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?