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.
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.
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:
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.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.
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.
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 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>
.
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 ""
.
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.
Caps are only useful if your code handles them gracefully, so know the shapes you'll get back:
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 403
until the tenant frees space. Deleting messages frees it back up, and retention pruning does that automatically over time.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.
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.rule_ids
. A tier can carry both a quota policy and a set of rules at once.429
/403
look like.nylas agent
, nylas workspace
, and nylas email
command set.