# Give your AI agent its own inbox: Nylas Agent Accounts via API and CLI > Source: > Published: 2026-06-21 18:41:28+00:00 Most "AI email" demos point a model at a human's inbox over OAuth. That's fine until you want the agent to *be* a participant — to have its own address that people reply to, that calendars invite, and that builds its own sender reputation. Pointing at someone's personal inbox doesn't give you that. Nylas **Agent Accounts** take the other approach: a real `name@yourdomain.com` mailbox and calendar that the agent owns end to end. It sends, receives, hosts events, and RSVPs — and to anyone on the other side it's indistinguishable from a human-operated account. It went GA in June 2026. The part I like as an SRE: it's not a new API surface. An Agent Account is just another Nylas [grant](https://developer.nylas.com/docs/v3/auth/). It gets a `grant_id` that works with every endpoint you already use — Messages, Drafts, Threads, Folders, Attachments, Calendars, Events, Webhooks. Nothing new to learn on the data plane. This walkthrough provisions one two ways (CLI and raw API), then sends, receives, RSVPs, and adds guardrails. When you create an Agent Account, Nylas provisions a real mailbox on a domain you've registered (or a Nylas `*.nylas.email` trial domain). Each account comes with: `inbox` , `sent` , `drafts` , `trash` , `junk` , `archive` ), plus any custom ones you create`grant_id` for all the existing Nylas endpointsYou need two things: `nylas init` creates an account and generates a key in one command.`*.nylas.email` trial subdomain (good for testing in minutes) or your own custom domain with MX + TXT records. Register it under Organization Settings → Domains.Why your own domain? It's what makes the agent a real first-class sender instead of a shared relay address — people reply to it, calendars invite it, and its mail authenticates as coming from you. A new domain builds sender reputation over roughly four weeks of gradual sending, so run one domain per customer or use case to keep reputations isolated. After `nylas init` , provisioning is one command: ``` nylas agent account create test@your-application.nylas.email ``` The CLI prints the new grant ID alongside connector and status details. A few companion commands: ``` # List every agent account nylas agent account list # Confirm the connector is ready nylas agent status # Show one account nylas agent account get test@your-application.nylas.email # See how accounts, workspaces, policies, rules, and lists fit together nylas agent overview ``` That last one — `nylas agent overview` — renders a tree per account and flags dangling references to deleted policies/rules. It's the command I'd reach for first when something looks misconfigured. Under the hood the CLI calls [ POST /v3/connect/custom](https://developer.nylas.com/docs/reference/api/manage-grants/byo_auth/) with `"provider": "nylas"` — the same Bring Your Own Auth endpoint used for other providers, minus the refresh token. Just the email on a registered domain: ``` curl --request POST \ --url "https://api.us.nylas.com/v3/connect/custom" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "provider": "nylas", "name": "Test Agent", "settings": { "email": "test@your-application.nylas.email" } }' ``` The response contains a `grant_id` — **save it**, you'll use it everywhere. The top-level `name` sets the display name recipients see on outbound mail (`Test Agent ` ). Omit it and the account sends with no display name. Two ways, same as any grant. **Poll the messages endpoint:** ``` curl --request GET \ --url "https://api.us.nylas.com/v3/grants//messages?limit=5" \ --header "Authorization: Bearer " ``` **Or subscribe to a webhook** so Nylas calls you the moment mail arrives. From the CLI: ``` nylas webhook create \ --url https://yourapp.example.com/webhooks/nylas \ --triggers message.created ``` Inbound mail fires the standard `message.created` webhook — identical in shape to `message.created` for any other grant, so a handler you already have just works. On top of that, Agent Accounts emit deliverability webhooks like `message.delivered` , `message.bounced` , and `message.complaint` for tracking outbound mail. Same `/messages/send` endpoint you'd use for a connected grant: ``` curl --request POST \ --url "https://api.us.nylas.com/v3/grants//messages/send" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "subject": "Hello from my Agent Account", "body": "This message was sent by a Nylas Agent Account.", "to": [{ "email": "you@yourdomain.com", "name": "You" }] }' ``` The recipient sees a normal message from the agent's address — no "sent via" branding, no relay footer. Every Agent Account ships with a primary calendar, reachable through the same Events endpoints: `GET /v3/grants/{grant_id}/events` — list events`POST /v3/grants/{grant_id}/events` — create an event and invite others`POST /v3/grants/{grant_id}/events/{id}/send-rsvp` — accept or decline an invitationInvitations travel over standard iCalendar/ICS, so Google Calendar, Microsoft 365, and Apple Calendar all treat the agent as a normal participant. This is what lets a scheduling agent propose slots and have participants accept them as ordinary invites. Provisioning gives you a working mailbox. The interesting operational part is constraining what it can do. Three application-scoped resources handle that: `block` , `mark_as_spam` , `assign_to_folder` , `archive` , or `trash` .`in_list` operator.They attach through **workspaces**, not individual grants: a workspace carries one `policy_id` and an array of `rule_ids` , and every account in it inherits both. Each application has a default workspace, so configuring it governs all your unassigned accounts at once. Inspect them from the CLI: ``` nylas agent policy list nylas agent rule list nylas agent list list ``` And create each piece from the CLI: ``` # A typed list of domains you can reference from a rule's in_list condition nylas agent list create --name "Blocked domains" --type domain --item spam.com # An outbound rule that archives the sent copy of mail to a recipient domain nylas agent rule create \ --name "Archive outbound mail" \ --trigger outbound \ --condition recipient.domain,is,example.com \ --action archive # A policy you can attach to a workspace nylas agent policy create --name "Strict Policy" ``` Swap `--action archive` for `--action block` and the rule rejects the message instead — before it ever reaches the mailbox (inbound) or the provider (outbound). That's handy for data-loss prevention, keeping test domains out of production, or stopping an agent from emailing the wrong people. Inbound and outbound rules are isolated: inbound rules never run on sends, and outbound rules never re-evaluate the stored sent copy. Policies are optional. Skip them and the account runs at your billing plan's maximum limits and delivers every inbound message to the inbox. | Dimension | Default | Notes | |---|---|---| | Send rate | 200 messages/account/day | Paid plans have no daily cap by default | | Storage | 3 GB/org | Higher on paid plans | | Retention | 30 days inbox, 7 days spam | Configurable via policy | | Domains | Unlimited | One application can manage accounts across any number of domains | The thing that makes Agent Accounts click is that there's no second system. You provision an identity with one CLI command or one API call, and from that point it's the same Messages, Events, and Webhooks surface you'd use for a connected Gmail or Microsoft grant — now owned by your agent instead of borrowed from a user. If you want to go deeper: *Written by Qasim Muhammad and Pouya Sanooei.*