Skip to content
Skip to main content

Nylas Agent Accounts

Last updated:

Nylas Agent Accounts are a standalone Nylas product: fully functional email and calendar identities that you create and control through the API, with no user accounts to connect. Each Agent Account is a real [email protected] mailbox — it sends and receives email, hosts and responds to calendar events, and is indistinguishable from a human-operated account to anyone interacting with it.

This is a different model from pointing an AI agent at a human’s inbox. An Agent Account gives the agent a first-class identity — its own address, its own mailbox, its own calendar — that people and other agents communicate with directly. Think of it the way you’d think of any other user in your organization: reachable, persistent, and accountable for its own interactions.

Under the hood, an Agent Account is just another grant. It gets a grant_id that works with every existing Nylas endpoint — Messages, Drafts, Threads, Folders, Attachments, Calendars, Events, Webhooks — so anything you’ve built for connected accounts works for Agent Accounts with no new concepts.

How teams use Agent Accounts

Section titled “How teams use Agent Accounts”

Sales outreach agent. A [email protected] mailbox runs cold outreach campaigns, threads replies through the Messages API, and classifies responses (interested / not now / unsubscribe) with an LLM. When a prospect says yes to a meeting, the same grant creates an event on the agent’s own calendar and sends the invite.

Customer support triage. A [email protected] Agent Account receives every inbound support email. Rules block known spam domains at the SMTP stage, auto-route invoices to a finance folder, and mark VIP senders for immediate attention. An LLM drafts replies to common questions; humans approve the sensitive ones via a webhook flow.

Scheduling bot with its own calendar. A scheduling agent owns [email protected], parses meeting requests with an LLM, checks availability against its own calendar, proposes slots, and creates events that participants accept as normal invitations. See the scheduling-agent tutorial.

Agent signup and testing. A test agent provisions a fresh inbox per run, signs up for a third-party service, receives the verification email, extracts the link or OTP, and completes onboarding — no human in the loop. The inbox gets torn down when the test ends. See the signup automation recipe.

Voice-to-email follow-up. A voice agent taking support calls sends documents, reset instructions, or meeting recaps from its own [email protected] address the moment the caller asks. The reply returns through the same Agent Account so the full conversation is one thread in the mailbox.

Per-customer agent identities. A multi-tenant app provisions one Agent Account per customer on each customer’s own verified domain — [email protected], [email protected] — each with its own policy, send quota, and sender reputation. All of them run in one Nylas application with the same code path.

Application email that can take a reply. Product email usually leaves through a send-only provider from a no-reply address. Run it through an Agent Account instead, or pair transactional send with one on the same domain, and password resets and receipts go out from a real mailbox where anything the customer writes back is readable through the same grant. The Auth0 and Supabase recipes wire this into an existing auth stack, and migrating from a transactional provider covers the cutover.

How Agent Accounts work

Section titled “How Agent Accounts work”

When you create an Agent Account, Nylas provisions a real mailbox on a domain you’ve registered (or on a Nylas-provided *.nylas.email trial domain). The account gets:

  • An email address that can send outbound mail and receive inbound mail like any other mailbox.
  • Six system folders provisioned automatically (inbox, sent, drafts, trash, junk, archive), plus any custom folders you create.
  • A primary calendar that can host events and RSVP to invitations over standard iCalendar/ICS.
  • A grant_id you use with the existing Nylas endpoints for messages, events, attachments, and webhooks.

How an Agent Account receives email

Mail reaches the Agent Account through your domain's MX record. Nylas filters it, stores it in a folder, and sends your agent a message.created webhook with the message's thread_id.
Diagram as text
  • Sender: External sender: Any mail server, including Gmail, Outlook, or another agent.
  • Your DNS: Your domain's MX record: Points mail for the Agent Account's domain at Nylas. (Sends email)
  • Nylas: Inbound block rules: Rules match on the sender's address, domain, or TLD. (Delivers over SMTP)
    • block rule matches → Rejected at SMTP: The sender's server gets the rejection. Nothing is stored.
  • Nylas: Spam filtering: Checks the sender's SPF, DKIM, and DMARC, plus DNS blocklists. (Accepted)
  • Nylas: Agent Account mailbox: Stored in Inbox, Junk, or a rule's folder, and added to a thread. (Scored as spam or not)
    • Message carries a calendar invite → Event on the primary calendar: Created only when the organizer's address passes sender authentication. Fires event.created.
  • Your agent: Your agent handles it: Fetches the thread for context, then decides how to respond. (message.created webhook with thread_id)

How an Agent Account sends email

Your agent sends through the Messages API. Nylas checks the domain, rules, and quotas, delivers the message from your domain, and reports delivery results back as webhooks.
Diagram as text
  • Your agent: Send a message: Pass reply_to_message_id to reply in an existing thread.
  • Nylas: Send endpoint: POST /v3/grants/{grant_id}/messages/send, or send a draft. (API request)
  • Nylas: Send checks: Verified sender domain, outbound rules, and send quotas. (Validate)
    • Blocked → Send blocked: 403: unverified sender domain or an outbound block rule.
    • Over a limit → Limit reached: 429: daily, monthly, or per-second send limit.
  • Nylas: Signed and delivered: DKIM-signed from your domain, with threading headers on replies. (Passed)
    • Stores a copy → Sent folder: The sent copy joins the thread and fires message.created.
  • Recipient: Recipient's mail server: Replies thread back to the Agent Account through the inbound path. (Delivered over SMTP)

You create Agent Accounts three ways: with the Nylas CLI (nylas agent account create <email>), from the Dashboard, or with POST /v3/connect/custom using "provider": "nylas" — the same Bring Your Own Authentication endpoint used for other providers. Pass a top-level name to give the account a display name that recipients see on outbound mail. You can optionally pass a workspace_id at creation to place the account in a workspace. The policy and rules on that workspace apply limits, spam detection, and inbound rules, and Nylas evaluates its outbound rules each time the account sends.

Inbound mail fires the standard message.created webhook, identical in shape to message.created for any other grant.

Why an Agent Account uses your own domain

Section titled “Why an Agent Account uses your own domain”

Every Agent Account sends and receives on a domain you control, either a custom domain like agents.yourcompany.com or a Nylas-provided *.nylas.email trial domain. Using your own domain is what makes the agent a real, first-class sender instead of a shared address: people reply to it, calendars invite it, and its mail is authenticated as coming from you. It also means the account builds its own sender reputation, which a new domain establishes over about 4 weeks of gradual sending. Run one domain per customer or per use case to keep those reputations isolated, and see Email deliverability for Agent Accounts to protect and warm it.

What you can do

Section titled “What you can do”
CapabilityDescriptionPage
Set up a domainRegister a custom domain and publish the DNS records Nylas needs to verify it.Setup domains
Provision accountsCreate Agent Accounts on a verified domain — from the CLI (nylas agent account create), the Dashboard, or the API.Provisioning Agent Accounts
Send and receive emailUse the same /messages and /messages/send endpoints you use for connected grants. Inbound attachment limits are set by your plan and the grant’s policy; outbound messages are capped at 25 MB total.Messages API
Host calendar eventsCreate events, accept invitations, and RSVP on the primary calendar through the Events API.Events API
Manage contactsRead, create, update, and delete the account’s own contacts through the Contacts API, and react to contact webhooks.Agent Account contacts
Apply policiesBundle limits, spam detection, retention, and linked inbound rules; assign one policy to many accounts.Policies, Rules, and Lists
Filter inbound and outbound mailMatch on sender fields for inbound rules, or sender, recipient, and outbound.type for outbound rules, then run actions like block, mark_as_spam, or assign_to_folder.Policies, Rules, and Lists
Maintain allow/block listsTyped collections of domains, TLDs, or addresses that rules reference through the in_list operator.Policies, Rules, and Lists
Receive webhooksSubscribe to message.created and the other grant-scoped triggers to be notified of inbound mail, state changes, and calendar activity. On top of those, Agent Accounts emit deliverability webhooks like message.delivered, message.bounced, and message.complaint to track outbound mail.Webhooks
Expose IMAP and SMTPGive end users direct mail-client access to the Agent Account over standard IMAP and SMTP submission, alongside the API.Mail client access

Known limits

Section titled “Known limits”
DimensionDefaultNotes
Send rate200 messages per account per day on the free planPaid plans have no daily cap by default. A stricter quota can be set through a policy.
Storage3 GB per organization on the free planHigher storage available on paid plans.
Retention30 days inbox, 7 days spam on the free planConfigurable through policy retention limits.
Multi-domainUnlimitedOne Nylas application can manage Agent Accounts across any number of registered domains.

Before you begin

Section titled “Before you begin”

To provision Agent Accounts, you also need a domain registered with Nylas — either a Nylas-provided *.nylas.email trial subdomain or your own custom domain with MX and TXT records configured. See Setup domains.

Section titled “Related resources”