Agent Accounts Beta: Limits and Gotchas

Thirteen new API operations in a single beta drop. That's the headline number from the April 16 changelog that introduced Agent Accounts — and the size of that policy surface tells you where the API is newest, which is exactly where a beta user should tread carefully. This post is the everything-beta-about-the-beta rundown: what shipped, the current limits, the gotchas, and how to build so general availability doesn't break you.

What shipped on April 16

The release made Agent Accounts the productized successor to the earlier Inbound beta (existing Inbound grants keep working). The core pieces:

• A new grant type. An Agent Account is a real [e-mail] mailbox that sends, receives, hosts calendar events, and uses the same grant_id contract as any connected account.
• Three provisioning paths. CLI, Dashboard, or POST /v3/connect/custom with the Agent Account variant — which accepts email, a policy reference, and an optional app_password for IMAP/SMTP access.
• Policies, Rules, and Lists. Those 13 operations: full CRUD under /v3/policies, /v3/rules, and /v3/lists, plus item management at /v3/lists/{id}/items. Policies define what an agent can do; rules apply conditional logic to mail; lists hold the values rules reference.
• An audit trail. GET /v3/grants/{grant_id}/rule-evaluations returns a time-ordered record of every rule that fired — matched conditions and action taken — so you can debug why a message was blocked or routed.

That last one deserves a moment, because it's the piece most beta users skip and then wish they hadn't. When a message silently vanishes into junk or never arrives at all, this is the endpoint that tells you which rule did it:

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

Wire it into your debugging runbook on day one. "Why was this blocked?" is a question you'll ask during beta more than at any other time.

The limits as they stand today

From the overview's known-limits table: 200 messages per account per day on the free plan (paid plans have no daily cap by default), 3 GB of storage per organization, and retention of 30 days for inbox plus 7 days for spam — both configurable through a policy. Domains are unlimited; one application can manage accounts across as many registered domains as you like.

Message size has its own ceilings: outbound messages are capped at 40 MB total, and inbound attachment limits are set by your plan and the grant's policy. Attachments over the policy caps are dropped from the message — the message itself still delivers and the webhook still fires, which is exactly the kind of quiet partial-success behavior you want to know about before production.

Treat every one of those numbers as a snapshot. Beta limits are the kind of thing that gets tuned on the way to GA, in either direction.

The gotchas

Not everything works on these grants. The supported-endpoints reference exists precisely because there's an explicit unsupported set: Scheduler, Notetaker, and a handful of provider-only features don't run against an Agent Account. If your roadmap assumes booking pages on an agent mailbox, check the list before you architect around it.

The policy layer is the newest layer. The changelog marks Agent Accounts, the Policies/Rules/Lists APIs, and the BYO Auth variant as beta — "shapes and semantics may change before general availability." In practice, the messages-and-calendars surface is old and settled; the governance surface is weeks old. Expect churn where the code is youngest.

The policy attachment model already moved. The April changelog describes the provisioning variant accepting a policy_id directly. The current provisioning docs attach policies through workspaces instead: you pass a top-level workspace_id at creation, and the account inherits that workspace's policy limits, spam settings, and rules. Omit it and the account is auto-grouped by domain or dropped into your application's default workspace. This is beta drift happening in real time, in public, between a changelog and the docs it links to — and it's the single strongest argument here for wrapping the governance surface.

App passwords are write-only. If you set an app_password for IMAP/SMTP access, it must be 18–40 printable ASCII characters with at least one uppercase letter, one lowercase letter, and one digit — and it's stored as a bcrypt hash, so you can never retrieve it later, only reset it. Generate it, store it in your secrets manager at creation time, or plan on resets.

Even the CLI moved during beta. The April changelog says nylas agent create; the current provisioning docs say nylas agent account create. Tiny, but it's a preview of the kind of drift you're signing up for — pin your CLI version in CI and read release notes.

Replaced-beta history matters. This is the second iteration of the idea (Inbound came first). Teams on the earlier beta got continuity, which is a good sign for how the transition to GA will be handled — but "continues to work" and "is the recommended path" aren't the same thing. Build on the new names.

Building so GA doesn't break you

The stable foundation is the grant contract. An Agent Account is deliberately just another grant, so Messages, Drafts, Threads, Folders, Calendars, Events, and Webhooks — endpoints that predate this beta by years — work unchanged. Code written against grant_id is the safest code you'll write this quarter.

Three defensive habits for the rest:

1. Isolate the beta surface. Put every call to /v3/policies, /v3/rules, and /v3/lists behind one module in your codebase. If a shape changes, you patch one file.
2. Branch on provider. Agent Account grants report provider: "nylas". Webhook handlers that branch on it keep working no matter what else changes around them.
3. Don't hardcode the limits. Read quota and retention behavior from your policy configuration rather than baking 200-per-day assumptions into business logic.

So, build on it?

My take: yes, for anything where the mailbox primitive is the value — the grant-level surface is mature and the beta risk is concentrated in governance APIs you can wrap. Hold off only if your design leans hard on policy semantics you can't afford to revisit.

Start with the overview and limits table, wrap the 13 policy operations behind your own interface, and subscribe to the changelog feed. What's your personal threshold for shipping production code on a beta API — and has a GA transition ever actually burned you?