{"slug": "set-per-customer-send-quotas-with-agent-policies", "title": "Set per-customer send quotas with agent policies", "summary": "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.", "body_md": "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.\n\nFree-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.\n\nWith 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.\n\nI 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.\n\nAn **Agent Account** is just a Nylas grant with a `grant_id`\n\n— 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.\n\nA **policy** is a reusable bundle of limits and spam settings. One policy can govern many accounts. The limits we care about for tiering are:\n\n`limit_count_daily_email_sent`\n\n— how many messages an account can send per day.`limit_storage_total`\n\n— total stored bytes per account.`limit_inbox_retention_period`\n\n— days a message stays in the inbox before deletion.`limit_spam_retention_period`\n\n— days a message stays in spam before deletion (must be shorter than the inbox window).A **workspace** carries exactly one `policy_id`\n\n. 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.\n\nThat's the whole idea. The rest of this post is plumbing.\n\nYou 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:\n\n`429 too_many_requests`\n\nwhen an account is over. If you also count, you now have two sources of truth that disagree at the edges.`limit_storage_total`\n\ncaps 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.\n\nThe 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.\n\nYou'll need a Nylas API key and a registered domain to provision Agent Accounts against (a custom domain, or a `*.nylas.email`\n\ntrial subdomain). New domains warm over roughly four weeks, so don't expect day-one volume.\n\nThe examples use `https://api.us.nylas.com`\n\nas the base host and `Authorization: Bearer <NYLAS_API_KEY>`\n\nfor auth. Swap in the EU host if that's your region.\n\nOne 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`\n\n, `/v3/workspaces`\n\n). That's different from everything in the Messages/Drafts world, which is always scoped under `/v3/grants/{grant_id}/...`\n\n.\n\nIf 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/).\n\nStart 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.\n\nA 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\n\n`nylas agent policy create --name \"...\"`\n\ncreates an Here's the free-tier policy over HTTP:\n\n```\ncurl --request POST \\\n  --url \"https://api.us.nylas.com/v3/policies\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"name\": \"Free tier\",\n    \"limits\": {\n      \"limit_count_daily_email_sent\": 200,\n      \"limit_storage_total\": 3221225472,\n      \"limit_inbox_retention_period\": 30,\n      \"limit_spam_retention_period\": 7\n    }\n  }'\n```\n\n`3221225472`\n\nis 3 GB in bytes — storage limits are bytes, not gigabytes, so do the multiplication (`3 * 1024^3`\n\n). The response hands back the policy `id`\n\n; hold onto it.\n\nThe CLI equivalent passes the same JSON through `--data`\n\n:\n\n```\nnylas agent policy create --data '{\n  \"name\": \"Free tier\",\n  \"limits\": {\n    \"limit_count_daily_email_sent\": 200,\n    \"limit_storage_total\": 3221225472,\n    \"limit_inbox_retention_period\": 30,\n    \"limit_spam_retention_period\": 7\n  }\n}'\n```\n\nNow 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.\n\n```\ncurl --request POST \\\n  --url \"https://api.us.nylas.com/v3/policies\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"name\": \"Enterprise tier\",\n    \"limits\": {\n      \"limit_count_daily_email_sent\": 5000,\n      \"limit_storage_total\": 10737418240,\n      \"limit_inbox_retention_period\": 365,\n      \"limit_spam_retention_period\": 30\n    }\n  }'\n```\n\nAnd the same with the CLI:\n\n```\nnylas agent policy create --data '{\n  \"name\": \"Enterprise tier\",\n  \"limits\": {\n    \"limit_count_daily_email_sent\": 5000,\n    \"limit_storage_total\": 10737418240,\n    \"limit_inbox_retention_period\": 365,\n    \"limit_spam_retention_period\": 30\n  }\n}'\n```\n\n`10737418240`\n\nis 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.\n\nTo inspect what you've got, list all policies or read one back by ID. Over HTTP that's `GET /v3/policies`\n\nand `GET /v3/policies/{policy_id}`\n\n:\n\n```\ncurl --request GET \\\n  --url \"https://api.us.nylas.com/v3/policies\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\"\n\ncurl --request GET \\\n  --url \"https://api.us.nylas.com/v3/policies/<POLICY_ID>\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\"\n```\n\nThe CLI equivalents are `nylas agent policy list`\n\nand `nylas agent policy get <policy-id>`\n\n.\n\nA 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.\n\nOver HTTP, `name`\n\nand `domain`\n\nare the required fields; `policy_id`\n\nattaches the policy at creation time:\n\n```\ncurl --request POST \\\n  --url \"https://api.us.nylas.com/v3/workspaces\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"name\": \"Free tier\",\n    \"domain\": \"yourcompany.com\",\n    \"policy_id\": \"<FREE_POLICY_ID>\"\n  }'\n```\n\nThe CLI takes the same fields as flags — `--name`\n\nand `--domain`\n\nare both required, `--policy-id`\n\nattaches the policy:\n\n```\nnylas workspace create \\\n  --name \"Free tier\" \\\n  --domain yourcompany.com \\\n  --policy-id <FREE_POLICY_ID>\n```\n\nRepeat for enterprise, pointing at the enterprise policy:\n\n```\nnylas workspace create \\\n  --name \"Enterprise tier\" \\\n  --domain yourcompany.com \\\n  --policy-id <ENTERPRISE_POLICY_ID>\n```\n\nIf 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:\n\n```\ncurl --request PATCH \\\n  --url \"https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"policy_id\": \"<ENTERPRISE_POLICY_ID>\"\n  }'\n```\n\nAnd with the CLI:\n\n```\nnylas workspace update <WORKSPACE_ID> --policy-id <ENTERPRISE_POLICY_ID>\n```\n\nThis `update`\n\npath 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.\n\nTo detach a policy entirely and fall back to plan maximums, clear the `policy_id`\n\n. The API takes an explicit `null`\n\n:\n\n```\ncurl --request PATCH \\\n  --url \"https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"policy_id\": null\n  }'\n```\n\nThe CLI uses an empty string to mean the same thing: `nylas workspace update <WORKSPACE_ID> --policy-id \"\"`\n\n.\n\nNow 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.\n\nThe straightforward path: create the account, then move it into the right workspace. Creating an Agent Account is a `POST /v3/connect/custom`\n\nwith `\"provider\": \"nylas\"`\n\nand a `settings.email`\n\non your registered domain:\n\n```\ncurl --request POST \\\n  --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"provider\": \"nylas\",\n    \"name\": \"Acme Support Bot\",\n    \"settings\": { \"email\": \"support@acme.yourcompany.com\" }\n  }'\n```\n\nThe CLI wraps all of that — connector setup included — behind one command:\n\n```\nnylas agent account create support@acme.yourcompany.com --name \"Acme Support Bot\"\n```\n\nA 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`\n\nand a `domain`\n\nthat 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.\n\nTo put a new account into a specific tier, move it. The CLI has a first-class `move`\n\n:\n\n```\nnylas agent account move support@acme.yourcompany.com --workspace <ENTERPRISE_WORKSPACE_ID>\n```\n\nThe 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`\n\n:\n\n```\ncurl --request PATCH \\\n  --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"workspace_id\": \"<ENTERPRISE_WORKSPACE_ID>\"\n  }'\n```\n\nThe second path skips the move entirely: **auto-grouping by domain.** Create a workspace with `auto_group: true`\n\nand a `domain`\n\n, and any new Agent Account whose email domain matches joins it automatically. If you give each tier its own subdomain — say `free.yourcompany.com`\n\nand `enterprise.yourcompany.com`\n\n— you can make tier placement a function of the address you provision, and never call `move`\n\nat all. Set `\"auto_group\": true`\n\nwhen you create the workspace over HTTP:\n\n```\ncurl --request POST \\\n  --url \"https://api.us.nylas.com/v3/workspaces\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"name\": \"Enterprise tier\",\n    \"domain\": \"enterprise.yourcompany.com\",\n    \"policy_id\": \"<ENTERPRISE_POLICY_ID>\",\n    \"auto_group\": true\n  }'\n```\n\nOr, with the CLI, add the `--auto-group`\n\nflag:\n\n```\nnylas workspace create \\\n  --name \"Enterprise tier\" \\\n  --domain enterprise.yourcompany.com \\\n  --policy-id <ENTERPRISE_POLICY_ID> \\\n  --auto-group\n```\n\nPick the model that fits your provisioning flow. Explicit `move`\n\nis easier to reason about when one domain serves every tier; auto-grouping is cleaner when your addressing scheme already encodes the tier.\n\nCaps are only useful if your code handles them gracefully, so know the shapes you'll get back:\n\n`POST /v3/grants/{grant_id}/messages/send`\n\nreturns `429`\n\nwith type `too_many_requests`\n\n. 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`\n\nuntil the tenant frees space. Deleting messages frees it back up, and retention pruning does that automatically over time.Treat the `429`\n\nlike 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`\n\nor a policy swap on the workspace. No data migration, no re-provisioning.\n\n`limit_count_daily_email_sent: 200`\n\nmeans 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`\n\n. A tier can carry both a quota policy and a set of rules at once.`429`\n\n/`403`\n\nlook like.`nylas agent`\n\n, `nylas workspace`\n\n, and `nylas email`\n\ncommand set.", "url": "https://wpnews.pro/news/set-per-customer-send-quotas-with-agent-policies", "canonical_source": "https://dev.to/mqasimca/set-per-customer-send-quotas-with-agent-policies-nhf", "published_at": "2026-06-28 00:35:49+00:00", "updated_at": "2026-06-28 01:03:35.578589+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-infrastructure"], "entities": ["Nylas", "Nylas Agent Accounts", "Nylas CLI", "Nylas API"], "alternates": {"html": "https://wpnews.pro/news/set-per-customer-send-quotas-with-agent-policies", "markdown": "https://wpnews.pro/news/set-per-customer-send-quotas-with-agent-policies.md", "text": "https://wpnews.pro/news/set-per-customer-send-quotas-with-agent-policies.txt", "jsonld": "https://wpnews.pro/news/set-per-customer-send-quotas-with-agent-policies.jsonld"}}