Most multi-tenant email-agent setups give every customer the same caps. Your free-tier user who signed up an hour ago and your enterprise account doing thousands of sends a day hit the exact same daily send limit, the exact same storage ceiling, the exact same retention window. That's fine right up until a free trial account starts hammering your infrastructure, or an enterprise customer files a ticket because their agent stopped sending at noon UTC and nobody can explain why.

Free-tier and enterprise tenants shouldn't share the same caps. They have different risk profiles, different contractual obligations, and different billing. The trick is to make the quota a property of the tier, not a property of each individual account — so when you provision a new tenant you don't compute limits, you just drop them into the right bucket and the limits come along for free.

With Nylas Agent Accounts that bucket is a workspace, and the caps live on a policy you attach to it. Set up one policy per tier, attach each to its tier's workspace, and every Agent Account in that workspace inherits the policy's send, storage, and retention limits automatically. No per-account configuration, no drift.

I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for when I'm wiring this up. As always, I'll show both the raw HTTP call and the CLI equivalent for every step, because half of you live in scripts and the other half live in your app code.

What you actually get

An Agent Account is just a Nylas grant with a grant_id — a managed mailbox that can send and receive on a domain you've registered. Everything grant-scoped works against it: Messages, Drafts, Threads, Folders, the lot. There's nothing new to learn on the data plane.

A policy is a reusable bundle of limits and spam settings. One policy can govern many accounts. The limits we care about for tiering are:

• limit_count_daily_email_sent — how many messages an account can send per day.
• limit_storage_total — total stored bytes per account.
• limit_inbox_retention_period — days a message stays in the inbox before deletion.
• limit_spam_retention_period — days a message stays in spam before deletion (must be shorter than the inbox window).

A workspace carries exactly one policy_id. Every grant in the workspace inherits that policy. So the architecture is a short chain: policy → workspace → grants. Change the policy, and every account in the workspace moves with it. Move an account to a different workspace, and it picks up the new tier's caps the moment the move lands.

That's the whole idea. The rest of this post is plumbing.

Why this beats checking limits in your app

You could enforce quotas yourself — count sends in your own database, reject the request when a tenant goes over, run a nightly job to prune old mail. People do this. It works until it doesn't:

• Your counter and the provider's counter drift. Nylas already meters sends per account and returns 429 too_many_requests when an account is over. If you also count, you now have two sources of truth that disagree at the edges.
• You re-implement retention. Deleting old mail on a schedule is a cron job you have to write, monitor, and not break. Policies do it as a periodic prune you configure once.
• Storage is invisible to you. You don't actually know how many bytes a grant is holding at rest. Nylas does, and limit_storage_total caps it server-side.

Pushing the caps down to a policy means the enforcement happens where the resource lives. Your app code stays about what the agent does, not how much it's allowed to do. The part I like as an SRE is that the limit is declarative — it's a number on a policy, version it in your IaC, and the platform enforces it.

The honest tradeoff: policies are application-scoped admin resources, so you're managing a small set of them out-of-band from your per-tenant flow. That's the point — you want a handful of tier policies, not one policy per customer. If you find yourself creating a policy per tenant, you've taken a wrong turn; the per-tenant unit is the account, and the account's caps come from its workspace.

Before you begin

You'll need a Nylas API key and a registered domain to provision Agent Accounts against (a custom domain, or a *.nylas.email trial subdomain). New domains warm over roughly four weeks, so don't expect day-one volume.

The examples use https://api.us.nylas.com as the base host and Authorization: Bearer <NYLAS_API_KEY> for auth. Swap in the EU host if that's your region.

One thing worth internalizing up front: policies, rules, and workspaces have no grant ID in the path. Your API key identifies the application, and these resources live at the top level (/v3/policies, /v3/workspaces). That's different from everything in the Messages/Drafts world, which is always scoped under /v3/grants/{grant_id}/....

If you've never touched Agent Accounts before, the Agent Accounts overview is the place to start. The full limits and policy field reference is in Policies, Rules, and Lists.

Create a policy per tier

Start with the free tier. The plan defaults for Free are 200 sends/day, 3 GB storage, 30-day inbox retention, and 7-day spam retention — and that's already what an account runs at with no policy. So a "free" policy is mostly about making those defaults explicit so they're versioned and visible rather than implicit. The values below are simply the Free-plan defaults written down — 30-day inbox and 7-day spam retention are what Free already gives you, not a constraint I'm tightening. Paid tiers keep mail longer; Full Platform retains the inbox for 365 days and spam for 30.

A critical detail that trips people up: limit_* fields go in the policy's limits object, and you must pass the full body with --data on the CLI. A bare nylas agent policy create --name "..." creates an empty policy with no limits — it'll run at plan maximums, which is not what you want for a free tier.

Here's the free-tier policy over HTTP:

curl --request POST \
  --url "https://api.us.nylas.com/v3/policies" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Free tier",
    "limits": {
      "limit_count_daily_email_sent": 200,
      "limit_storage_total": 3221225472,
      "limit_inbox_retention_period": 30,
      "limit_spam_retention_period": 7
    }
  }'

3221225472 is 3 GB in bytes — storage limits are bytes, not gigabytes, so do the multiplication (3 * 1024^3). The response hands back the policy id; hold onto it.

The CLI equivalent passes the same JSON through --data:

nylas agent policy create --data '{
  "name": "Free tier",
  "limits": {
    "limit_count_daily_email_sent": 200,
    "limit_storage_total": 3221225472,
    "limit_inbox_retention_period": 30,
    "limit_spam_retention_period": 7
  }
}'

Now the enterprise tier. Higher daily send quota, more storage, longer retention. On Full Platform the per-account daily send cap is unlimited, but you almost certainly want a number anyway — an unbounded send quota on an agent is a great way to discover a runaway loop in production at scale. Pick a ceiling that's generous for the tier but not infinite.

curl --request POST \
  --url "https://api.us.nylas.com/v3/policies" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Enterprise tier",
    "limits": {
      "limit_count_daily_email_sent": 5000,
      "limit_storage_total": 10737418240,
      "limit_inbox_retention_period": 365,
      "limit_spam_retention_period": 30
    }
  }'

And the same with the CLI:

nylas agent policy create --data '{
  "name": "Enterprise tier",
  "limits": {
    "limit_count_daily_email_sent": 5000,
    "limit_storage_total": 10737418240,
    "limit_inbox_retention_period": 365,
    "limit_spam_retention_period": 30
  }
}'

10737418240 is 10 GB. Two rules the API enforces, so save yourself a round-trip: spam retention must be shorter than inbox retention, and you can't request a value above your plan's maximum — ask for more storage than your plan allows and the API rejects it.

To inspect what you've got, list all policies or read one back by ID. Over HTTP that's GET /v3/policies and GET /v3/policies/{policy_id}:

curl --request GET \
  --url "https://api.us.nylas.com/v3/policies" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

curl --request GET \
  --url "https://api.us.nylas.com/v3/policies/<POLICY_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

The CLI equivalents are nylas agent policy list and nylas agent policy get <policy-id>.

Create a workspace per tier and attach the policy

A policy does nothing on its own. It only takes effect when a workspace references it. So create one workspace per tier and attach the matching policy.

Over HTTP, name and domain are the required fields; policy_id attaches the policy at creation time:

curl --request POST \
  --url "https://api.us.nylas.com/v3/workspaces" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Free tier",
    "domain": "yourcompany.com",
    "policy_id": "<FREE_POLICY_ID>"
  }'

The CLI takes the same fields as flags — --name and --domain are both required, --policy-id attaches the policy:

nylas workspace create \
  --name "Free tier" \
  --domain yourcompany.com \
  --policy-id <FREE_POLICY_ID>

Repeat for enterprise, pointing at the enterprise policy:

nylas workspace create \
  --name "Enterprise tier" \
  --domain yourcompany.com \
  --policy-id <ENTERPRISE_POLICY_ID>

If you created a workspace before the policy existed, or you want to re-point an existing workspace at a different tier's policy, patch it. Over HTTP:

curl --request PATCH \
  --url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "policy_id": "<ENTERPRISE_POLICY_ID>"
  }'

And with the CLI:

nylas workspace update <WORKSPACE_ID> --policy-id <ENTERPRISE_POLICY_ID>

This update path is also how you change a whole tier's caps after the fact without touching a single account. Patch the workspace's policy to a new one — or update the policy's limits in place — and every grant in the workspace moves to the new numbers. That's the lever you pull when you renegotiate a tier or roll out new defaults.

To detach a policy entirely and fall back to plan maximums, clear the policy_id. The API takes an explicit null:

curl --request PATCH \
  --url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "policy_id": null
  }'

The CLI uses an empty string to mean the same thing: nylas workspace update <WORKSPACE_ID> --policy-id "".

Provision a tenant into its tier

Now the per-tenant flow, which is the part you'll run thousands of times. Provisioning a customer into a tier means putting their Agent Account in that tier's workspace. There are two ways in, and you'll likely use both.

The straightforward path: create the account, then move it into the right workspace. Creating an Agent Account is a POST /v3/connect/custom with "provider": "nylas" and a settings.email on your registered domain:

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",
    "name": "Acme Support Bot",
    "settings": { "email": "support@acme.yourcompany.com" }
  }'

The CLI wraps all of that — connector setup included — behind one command:

nylas agent account create support@acme.yourcompany.com --name "Acme Support Bot"

A new account that you don't place explicitly doesn't go straight to the default workspace. Nylas first tries to auto-group it by domain: if a custom workspace has auto_group: true and a domain that matches the account's email domain, the account joins that workspace. Only when no auto-group workspace matches does the account fall back to the application's default workspace. That default workspace runs accounts at plan maximums unless you've attached a policy to it — which, by the way, is a perfectly good move if "free tier" is your default: attach the free policy to the default workspace and every account that doesn't match an auto-group rule is automatically free-tier.

To put a new account into a specific tier, move it. The CLI has a first-class move:

nylas agent account move support@acme.yourcompany.com --workspace <ENTERPRISE_WORKSPACE_ID>

The target workspace's policy governs the account immediately — there's no propagation delay to wait through. Over HTTP, the move is a grant update that sets workspace_id:

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": "<ENTERPRISE_WORKSPACE_ID>"
  }'

The second path skips the move entirely: auto-grouping by domain. Create a workspace with auto_group: true and a domain, and any new Agent Account whose email domain matches joins it automatically. If you give each tier its own subdomain — say free.yourcompany.com and enterprise.yourcompany.com — you can make tier placement a function of the address you provision, and never call move at all. Set "auto_group": true when you create the workspace over HTTP:

curl --request POST \
  --url "https://api.us.nylas.com/v3/workspaces" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Enterprise tier",
    "domain": "enterprise.yourcompany.com",
    "policy_id": "<ENTERPRISE_POLICY_ID>",
    "auto_group": true
  }'

Or, with the CLI, add the --auto-group flag:

nylas workspace create \
  --name "Enterprise tier" \
  --domain enterprise.yourcompany.com \
  --policy-id <ENTERPRISE_POLICY_ID> \
  --auto-group

Pick the model that fits your provisioning flow. Explicit move is easier to reason about when one domain serves every tier; auto-grouping is cleaner when your addressing scheme already encodes the tier.

What a tenant sees when it hits a cap

Caps are only useful if your code handles them gracefully, so know the shapes you'll get back:

• Over the daily send quota: POST /v3/grants/{grant_id}/messages/send returns 429 with type too_many_requests. Nylas reserves the quota before sending and releases it if the send fails, so failed attempts don't count against the tenant. The counter resets at 00:00 UTC. One sharp edge worth a callout: an account that's over its send quota will still create calendar events successfully, but the invitation email is silently skipped — so watch the quota on agents that both email and schedule.
• Over the storage cap: storage-bound actions return 403 until the tenant frees space. Deleting messages frees it back up, and retention pruning does that automatically over time.
• Retention isn't an error your code sees at all — it's a background prune. Messages older than the inbox or spam window just disappear. Set the window per tier and forget it.

Treat the 429 like any rate limit: back off and retry after the window, or, if a tenant is legitimately outgrowing its tier, move them up a tier — which, in this design, is one nylas agent account move or a policy swap on the workspace. No data migration, no re-provisioning.

A few things to keep straight

• Limits are per account, not per workspace. limit_count_daily_email_sent: 200 means each grant in the free workspace gets 200 sends/day — not 200 shared across the tier. The policy is the template; the workspace is how you apply it to a group.
• One policy, many accounts — that's the win. Don't create a policy per customer. Create a policy per tier and let the workspace fan it out. If you have three tiers you have three policies, whether you serve ten tenants or ten thousand.
• Plan ceilings still apply on top. Per-account policy caps can only go stricter than your billing plan's maximums, never higher. Storage, bandwidth, and monthly send totals are also metered org-wide across every tier — the policy controls the per-account slice, not the org budget.
• Spam retention must be shorter than inbox retention. The API rejects the policy otherwise. Keep junk clearing out ahead of the inbox so it doesn't sit against the tenant's storage.
• Policies and rules live on the same workspace. If you're also doing inbound/outbound filtering with rules, they attach to the same workspace via rule_ids. A tier can carry both a quota policy and a set of rules at once.

What's next

• Policies, Rules, and Lists — every policy field, plus inbound/outbound rules and lists.
• Agent Account usage limits — the Free and Full Platform plan ceilings your policies sit under, and exactly what 429/403 look like.
• Provisioning Agent Accounts — creating accounts against a registered domain.
• Nylas CLI command reference — the full nylas agent, nylas workspace, and nylas email command set.