Set per-customer send quotas with agent policies

Nylas introduced per-customer send quotas for multi-tenant email agents using agent policies. The system allows setting different limits for free-tier and enterprise tenants by attaching policies to workspaces, which automatically apply to all agent accounts in that workspace. This approach moves quota enforcement to the platform, eliminating the need for per-account configuration and reducing drift.

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 https://developer.nylas.com/docs/v3/agent-accounts/ is the place to start. The full limits and policy field reference is in Policies, Rules, and Lists https://developer.nylas.com/docs/v3/agent-accounts/policies-rules-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.