DEV Community: Qasim Muhammad

One Agent Identity Per Customer: Multi-Tenant Email

Qasim Muhammad — Fri, 12 Jun 2026 00:53:32 +0000

Provisioning a tenant-scoped email identity for your SaaS is one POST:

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",
    "workspace_id": "<WORKSPACE_ID>",
    "settings": {
      "email": "scheduling@customer-a.com"
    }
  }'

No OAuth dance, no refresh token — just an address on a registered domain. The response comes back already valid:

{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
  "data": {
    "id": "b1c2d3e4-5678-4abc-9def-0123456789ab",
    "provider": "nylas",
    "grant_status": "valid",
    "email": "scheduling@customer-a.com",
    "scope": [],
    "created_at": 1742932766
  }
}

The data.id is a grant_id that works with every existing Nylas endpoint, and the account is live immediately. That's the primitive behind a multi-tenant pattern worth knowing: one Agent Account per customer, on each customer's own verified domain, all managed from a single application. (Agent Accounts are in beta, so the surface may shift before GA.)

The architecture in one paragraph

Your app runs scheduling@customer-a.com, scheduling@customer-b.com, and so on — same code path, different identities. Each account has its own policy, its own send quota, and its own sender reputation. A single application can manage accounts across an unlimited number of registered domains, so tenant count is a billing question, not an architectural one. Customer A's deliverability problems stay Customer A's; nothing they do contaminates Customer B's mail.

Domains: register once, mint accounts forever

The provisioning docs lay out two domain strategies you can mix freely in one application:

Strategy	Address format	Setup
Trial domain	`alias@<your-application>.nylas.email`	None — instant
Your own domain	`alias@yourdomain.com`	MX + TXT records at the DNS provider

For the per-customer pattern, each tenant brings their domain. You register it once per organization (picking the US or EU data center region), the customer publishes the MX record (routes inbound to the platform) and TXT records (ownership proof plus SPF/DKIM for outbound), and verification flips to verified automatically once DNS propagates. From then on you create as many accounts under it as your plan allows.

Two field-tested recommendations from the docs: prototype on *.nylas.email and move to custom domains before launch, and prefer a dedicated subdomain like agents.customer-a.com so agent sender reputation is isolated from the customer's primary marketing domain. The same mechanism handles environment separation — agents.staging.yourcompany.com next to agents.yourcompany.com on one application keeps staging traffic off the production domain. High-volume senders sometimes go further and shard outbound across sales-a.yourcompany.com, sales-b.yourcompany.com purely for reputation isolation.

Workspaces are the tenant boundary

Notice the workspace_id in the request up top. Policies and rules — send limits, spam detection, retention, inbound filtering — apply through workspaces, not individual grants. Place each tenant's accounts in their own workspace and the whole tenant inherits its policy in one move.

The placement rules are worth knowing precisely:

Pass workspace_id explicitly and the account lands there, picking up that workspace's limits, spam settings, and rules.
Omit it, and the account is auto-grouped into a workspace whose domain matches the email address (when auto_group is enabled), or falls back to your application's default workspace.
Move an existing account later with PATCH /v3/grants/{grant_id} and a new workspace_id.

For multi-tenant SaaS, that auto-group behavior is a nice default: accounts on customer-a.com cluster together without bookkeeping on your side. But explicit workspace_id per tenant is the predictable choice once policies differ between customers.

Fleet operations without leaving the terminal

The API call above is what your provisioning service runs; for day-to-day operations across tenants, the CLI exposes the same lifecycle:

nylas agent account create scheduling@customer-a.com
nylas agent account list --json
nylas agent account get scheduling@customer-a.com
nylas agent status              # connector readiness
nylas agent policy list         # policies attached to accounts
nylas agent account delete scheduling@customer-a.com --yes

Agent Accounts also show up in nylas auth list alongside connected OAuth grants, which is a useful reminder of the design: to the rest of the platform, a tenant's agent is just another grant. There's a Dashboard path too (Agent Accounts → Accounts → Create account), handy for support staff who need to inspect a tenant's inbox without shipping code.

Quotas and the optional human door

Per-tenant quota math starts from the platform defaults: 200 messages per account per day on the free plan (paid plans have no daily cap by default), and a stricter per-workspace quota can be set through a policy when a tenant's use case warrants it. Storage runs 3 GB per organization on the free plan, with more on paid tiers.

If a tenant wants their staff to supervise the agent's mailbox from Outlook or Apple Mail, set an app_password at creation — 18–40 printable ASCII characters with at least one uppercase letter, one lowercase letter, and one digit. It's bcrypt-hashed on write (you can reset it, never read it back), and without it, IMAP/SMTP access simply stays disabled. That's a sensible per-tenant toggle: API-only for most, protocol access for the customers who ask.

Verifying a tenant is live

After provisioning, the smoke test is satisfyingly boring: send a test email to the new address from any external client, then list the mailbox —

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?limit=5" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

If you've registered a message.created webhook, the notification arrives as mail lands, shaped identically to the same event for any connected grant — branch on provider: "nylas" when one handler serves both kinds of accounts.

Two questions that come up in design reviews

What happens if a tenant's domain verification stalls? Nothing breaks — the domain just stays unverified and you can't mint accounts on it yet. Registration is per-organization and verification flips automatically when DNS propagates, so the onboarding flow should poll domain status rather than assume it. Until then, the tenant can run on your trial domain.

Can we change a tenant's policy without touching accounts? Yes — that's the point of routing policy through workspaces. Swap or edit the workspace's policy and every Agent Account in it inherits the change; nothing is configured per-grant.

The end-to-end tenant onboarding flow — register domain, wait for verified, create workspace, provision account, smoke-test — is automatable from your existing provisioning code, and the trial-domain path lets you build it before any customer DNS exists. Sketch yours as a single idempotent onboardTenant(domain, alias) function and see how far one afternoon gets you.

Voice Agents That Follow Up by Email

Qasim Muhammad — Fri, 12 Jun 2026 00:53:25 +0000

Last sprint, a team I talked to demoed a voice agent that handled support calls impressively — right up until a caller asked "can you email me those instructions?" and the room went quiet. The agent could talk about the docs. It had no address to send them from. The workaround on the whiteboard afterwards was grim: relay through a shared noreply@, lose the replies, reconcile threads manually in the ticketing system.

Voice agents hit this wall constantly, because phone calls generate follow-up artifacts — reset instructions, documents, meeting recaps — and email is how callers expect to receive them. The clean fix is the same one that works for text agents: the voice agent gets its own mailbox.

The identity half

A Nylas Agent Account is a hosted mailbox you create through the API — Agent Accounts are in beta — and the voice use case from the product docs is exactly the scenario above: a voice agent taking support calls sends documents, reset instructions, or meeting recaps from its own voice-agent@yourcompany.com address the moment the caller asks. The part that makes it more than a send pipe: when the caller replies, the reply returns through the same account, so the full conversation is one thread in one mailbox. The phone call and its written follow-ups stop living in separate systems.

Each account is a real grant with a grant_id that works against the existing Messages, Threads, and Webhooks endpoints, ships with six system folders, and sends up to 200 messages per account per day on the free plan.

The plumbing half

The voice agents recipe covers how the runtime actually calls email tools. The flow is the same regardless of vendor:

speech → STT → LLM (function-calling) → subprocess(nylas …) → JSON → LLM → TTS → speech

The LLM decides on a tool, the runtime spawns a Nylas CLI subprocess with --json, the result comes back, and the model composes a spoken response. On LiveKit, a tool is just a decorated function:

from livekit.agents import function_tool
import subprocess

@function_tool()
async def list_recent_emails(limit: int = 5) -> str:
    """List the last few emails. Keep limit small for voice."""
    out = subprocess.run(
        ["nylas", "email", "list", "--limit", str(limit), "--json"],
        capture_output=True, text=True, timeout=30,
    )
    return out.stdout if out.returncode == 0 else "Could not fetch emails."

Vapi is the same idea over webhooks — Vapi posts JSON to your backend when the LLM calls a tool, your handler executes the CLI, and you return stdout in Vapi's envelope:

app.post("/vapi/tools", async (req, res) => {
  const { name, parameters } = req.body.message.toolCall;
  const args = ["nylas", "email", "list",
                "--limit", String(parameters.limit ?? 5),
                "--json"];
  const result = await execAsync(args, { timeout: 30000 });
  res.json({
    results: [{
      toolCallId: req.body.message.toolCall.id,
      result: result.stdout,
    }],
  });
});

Retell, Bland.ai, and OpenAI Realtime all follow the generic define-schema, dispatch-to-subprocess, return-JSON pattern. The recipe is explicit about why this beats running an MCP server next to the voice runtime: voice frameworks expect function-call-style tools that hand back a JSON blob, not a JSON-RPC peer. A side benefit of routing through the CLI: it absorbs every provider difference, so the same tools work whether the grants behind them are Gmail, Microsoft 365, Exchange, Yahoo, iCloud, IMAP — or an Agent Account.

Voice surfaces every UX mistake immediately

Four rules from the recipe, none optional:

Cap lists at 5. Reading a 50-message inbox aloud takes minutes. Default --limit 5 and let the caller say "more."
Summarize, don't read. Have the LLM produce "You've got three emails from Ada about the contract and a calendar invite from Rin" rather than narrating subject lines.
Confirm before send. Always. Speech-to-text mishears recipients and subjects in ways that send the wrong mail to the wrong person. The agent speaks the recipient, subject, and gist; only an explicit "yes" triggers the send tool:

   AGENT:  "Send to Ada at acme.test, subject 'pricing', body 'I'm in'?"
   USER:   "Yes."

Translate errors. "Error 401: invalid grant" is not a voice response. Map failures to "I couldn't reach email right now — you may need to re-authenticate."

And one rule that's really an SLA: every subprocess call needs a timeout, and 30 seconds is the right number. Voice users won't wait a minute; the framework's silence detection kicks in and the conversation falls apart. Aim for a round-trip under 2 seconds on the common tools — nylas email list --limit 5 --json clears that comfortably — and return a graceful spoken fallback when the timeout fires instead of bubbling the exception.

Why the dedicated address changes the product

Run the follow-up sends through the agent's own account rather than a borrowed human grant and three things improve at once:

Continuity. The caller replies to the recap, the reply lands in the agent's inbox, and the next interaction — voice or email — has the whole history in one thread.
Auditability. Every message the agent ever sent is sitting in its sent folder. The recipe separately recommends logging every send (recipient, subject, run ID, approval source) to your own store; the mailbox gives you the ground truth to reconcile against.
Multi-user routing stays sane. Voice platforms serving many users need per-user grant routing anyway — pass --api-key and --grant-id per command. The agent's outbound identity stays constant while the caller-side grants vary.

Quick answers

Can I use MCP instead of subprocess tools? If your runtime genuinely speaks MCP — Claude Code does, for example — yes, and the docs cover that path separately. Voice runtimes mostly don't, which is why the recipe defaults to subprocess + --json.

Where does the calendar fit? The same subprocess pattern covers nylas calendar events list, so "do I have anything tomorrow?" is one more decorated function, not a new integration.

A reasonable first milestone: wire one tool — send_recap — into your existing voice stack, pointed at an agent address on a trial domain, with the confirm-before-send exchange in the conversation script. Call it yourself, ask for the recap, and reply to the email it sends you. If the reply shows up threaded in the agent's inbox, you've got the loop. What would your voice agent send first — recaps, docs, or reset links?

How an AI Agent Can Sign Up for a Service on Its Own

Qasim Muhammad — Fri, 12 Jun 2026 00:53:20 +0000

An AI agent that can't receive email can't finish a signup form. That one limitation quietly rules out a huge class of autonomous workflows — the research agent that needs a developer account on a data source, the QA agent that registers for a SaaS on every test run, the purchasing agent that needs a buyer profile on a marketplace. Every one of them dies at "we've sent you a verification email."

The blocker was never the form. Headless browsers fill forms fine. The blocker is that verification emails traditionally route to a human inbox, which puts a human back in a loop that was supposed to have none.

Agent Accounts remove that dependency. The agent gets its own hosted mailbox (the feature is in beta), signs up with that address, catches the verification email via webhook, and completes onboarding by itself. Here's the whole flow, condensed from the cookbook recipe.

Provision, subscribe, sign up

Three setup moves. First, create the mailbox — one CLI command, or POST /v3/connect/custom with "provider": "nylas" if you'd rather hit the API:

nylas agent account create signup-agent@agents.yourdomain.com

The API version is the same Bring Your Own Authentication endpoint other providers use — no OAuth refresh token involved:

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",
    "settings": {
      "email": "signup-agent@agents.yourdomain.com"
    }
  }'

Save the grant ID it prints. Second, subscribe to inbound mail:

nylas webhook create \
  --url https://youragent.example.com/webhooks/signup \
  --triggers message.created

The message.created event fires within a second or two of mail arriving, carrying the message's summary fields. The webhook URL has to be publicly reachable over HTTPS; for local development, the recipe recommends VS Code port forwarding or Hookdeck to expose your dev server.

Third, submit the target service's signup form with the agent's address — a direct API call if the service exposes one, a Playwright/Puppeteer step if it doesn't, or a plain fetch POST when the endpoint is simple:

await fetch("https://saas-you-care-about.example.com/signup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "signup-agent@agents.yourdomain.com",
    name: "Automation Agent",
  }),
});

Catch the verification email

This is the part that used to require a human. Now it's a webhook handler with three filters and a regex:

app.post("/webhooks/signup", async (req, res) => {
  res.status(200).end();

  const event = req.body;
  if (event.type !== "message.created") return;

  const { grant_id, id: messageId, from } = event.data.object;
  if (grant_id !== AGENT_GRANT_ID) return;

  // Only react to mail from the service you signed up with.
  const sender = from[0]?.email ?? "";
  if (!sender.endsWith("@saas-you-care-about.example.com")) return;

  // Pull the full body (the webhook carries summary fields only).
  const resp = await fetch(
    `https://api.us.nylas.com/v3/grants/${AGENT_GRANT_ID}/messages/${messageId}`,
    { headers: { Authorization: `Bearer ${NYLAS_API_KEY}` } },
  );
  const message = (await resp.json()).data;

  const match =
    /https:\/\/saas-you-care-about\.example\.com\/confirm\?token=[^"\s<]+/.exec(
      message.body,
    );
  if (!match) return;

  await fetch(match[0]); // Complete the signup.
});

For multi-step confirmations, captchas, or OAuth redirects, swap the final fetch for a headless browser following the link. And if the service sends a code instead of a link, the parsing shape is identical — the OTP extraction recipe covers that variant.

The judgment calls the code doesn't show

The recipe's "things to know" section is where the real engineering lives:

Don't trust the first message that arrives. Lots of services send a "Welcome" email before the verification email. The handler above matches the sender and the expected URL pattern before clicking anything — keep both checks.

Lock the inbox down. Pair an allow-list of expected from.domain values with a block rule for everything else. If the agent's address ever leaks, the mailbox stays clean instead of becoming a spam magnet feeding garbage into your automation.

Verify webhook signatures. The handler above trusts req.body for brevity; in production, check the X-Nylas-Signature header on every POST before acting. A signup agent acts on what webhooks tell it, and an unverified webhook endpoint is an unauthenticated entry point into your automation.

Reuse or burn — pick deliberately. One account can serve many signup runs, or you can provision fresh per run and delete after. If you go per-run, teardown belongs in the happy path and the failure path:

nylas agent account delete signup-agent@agents.yourdomain.com --yes

Or, over the API, a plain DELETE /v3/grants/<AGENT_GRANT_ID> — the grant is the account, so deleting one deletes the other. Inactive grants accumulate, and "we'll clean those up later" is how every team ends up with 400 of them.

Know your quota. A free-plan account sends up to 200 messages per account per day, and inbound is generous but not infinite. A large test matrix should spread across multiple grants rather than reusing one.

Respect the terms of service. Programmatic signup is fine for your own testing and first-party integrations. Scraping third parties is a different conversation — nothing in the platform enforces this, but your legal team will care.

Why this pattern is bigger than signups

The verification-email catch is one instance of a general capability: the agent has a durable, addressable identity that other systems can send things to. Receipts, password resets, export-ready notifications, "your report is attached" emails — anything a service communicates over email becomes something an agent can act on, because the agent is reachable the same way a person is.

Some services keep talking after signup, too — follow-up confirmations, "complete your profile" nudges, billing notices. The same webhook handler grows into a full reply loop where the agent reads each message, decides, and responds from the same address it registered with.

The end-to-end loop — provision, register, verify, act — runs against a trial *.nylas.email domain with no DNS setup, so the experiment costs you a webhook endpoint and an afternoon. Pick one service your team signs up for manually today (a staging SaaS, an internal tool, a sandbox API) and automate exactly that signup. Which manual verification step would you kill first?

Extract OTP Codes From Email, Automatically

Qasim Muhammad — Fri, 12 Jun 2026 00:53:15 +0000

What does your automation do when the login flow it's driving sends a six-digit code instead of a confirmation link? For most teams the honest answer is "a human goes and checks a shared inbox," which is a strange bottleneck to leave in the middle of an otherwise fully automated pipeline.

There's a cleaner shape: the agent owns the mailbox the code lands in. With a Nylas Agent Account — a hosted mailbox controlled entirely through the API, currently in beta — the OTP email arrives, a webhook fires, your handler extracts the code, and whatever orchestrates the login gets it back. No human, no inbox-checking Slack message, no screen-scraping Gmail.

Step one: make sure it's the right email

A message.created webhook fires on every inbound message, so the first job is filtering down to the one that actually carries the code. The recipe uses two signals together — sender domain and a subject heuristic:

app.post("/webhooks/otp", async (req, res) => {
  res.status(200).end();

  const event = req.body;
  if (event.type !== "message.created") return;

  const msg = event.data.object;
  if (msg.grant_id !== AGENT_GRANT_ID) return;

  const sender = msg.from?.[0]?.email ?? "";
  const subject = msg.subject ?? "";

  const senderMatches = sender.endsWith("@no-reply.example.com");
  const subjectLooksRight = /code|verif|one.?time|passcode/i.test(subject);
  if (!senderMatches || !subjectLooksRight) return;

  await handleOtp(msg.id);
});

Neither check alone is enough. Sender-only matching trips on welcome emails from the same domain; subject-only matching trips on anything that mentions "verification."

Regex first, LLM second

Most OTP emails follow one of a few shapes: a standalone 4–8 digit number, or a code after a label like "Your code is:". Three patterns, tried in order from most to least specific, cover the vast majority of services:

const patterns = [
  /(?:code|passcode|one[\s-]?time)[^\d]{0,20}(\d{4,8})/i, // "Your code is: 123456"
  /\b(\d{6})\b/,        // bare 6-digit
  /\b(\d{4,8})\b/,      // bare 4–8 digit (last resort)
];

One detail that's easy to miss: strip the HTML before matching. Inline styles and hidden tracking pixels are full of digit sequences that will happily satisfy your last-resort pattern.

When regex strikes out — usually a code buried in a noisy marketing layout — fall back to a small LLM with a deliberately narrow prompt:

async function extractWithLlm(plaintext) {
  const response = await openai.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [
      {
        role: "system",
        content:
          "You extract one-time verification codes from email bodies. " +
          "Respond with JSON only: {\"code\": \"<the code>\"} or " +
          "{\"code\": null} if no code is present.",
      },
      { role: "user", content: plaintext.slice(0, 4000) },
    ],
    response_format: { type: "json_object" },
  });

  const parsed = JSON.parse(response.choices[0].message.content);
  if (parsed.code) return returnCode(parsed.code);
}

Only the first 4,000 characters of plaintext go in, and the model is asked for one thing in one shape — JSON with a code field or null. Don't ask the model to "understand" the email. Banking and enterprise senders sometimes rotate formats across sessions (6 digits, 8 digits, alphanumeric), and the LLM fallback is what absorbs those shifts without a regex update.

Getting the code back to whoever's waiting

The signup or login that triggered all this is blocked, waiting. The simplest bridge is a promise registry keyed by a correlation value — session ID, expected sender, run ID — with a timeout (the recipe defaults to 60 seconds):

export function awaitCode(correlationKey, timeoutMs = 60_000) {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      pending.delete(correlationKey);
      reject(new Error("OTP timeout"));
    }, timeoutMs);
    pending.set(correlationKey, { resolve, reject, timer });
  });
}

In production, swap the in-memory Map for a real queue or pub/sub — webhook handlers run on short-lived processes, and a restart between "code arrived" and "code consumed" loses the code.

The failure modes that actually bite

The recipe's warning list is the best part, because each item is a production incident in miniature:

Codes expire fast. Most services invalidate OTPs in 5–15 minutes. Check message.date freshness before returning a code — a slow agent will confidently hand back a dead one.
Multiple codes in the inbox. A stale code from an earlier attempt plus a fresh one means your regex can grab the wrong match. Sort by message timestamp, newest first, always.
Never log the code. OTPs are credentials. Log that one was received and returned; never the value.
Back off on failure. A tight retry loop requesting code after code looks like an attack from the service's side and gets the agent's address blocked.
Dedup redelivered webhooks. Nylas delivers webhooks at least once. A redelivered message.created can re-trigger extraction and hand a stale code back to a fresh login attempt — the duplicate-reply prevention patterns apply here too.

There's also a defense you set up before any of this code runs: lock the inbox down at the mail layer. Agent Account policies and rules can constrain inbound so only expected sender domains ever reach the agent's inbox. An OTP mailbox that accepts mail from anyone is an OTP mailbox someone will eventually try to confuse with look-alike messages; an allowlist makes the "match the right email" step mostly a formality.

Quick answers

What about magic links instead of codes? Same architecture, different regex — match a URL pattern instead of digits and follow the link instead of returning a value. The signup recipe covers that variant.

Why fetch the message body separately? The message.created webhook payload only carries summary fields — sender, subject, snippet. The full body comes from GET /v3/grants/{grant_id}/messages/{message_id}, which is the first call inside the extraction handler.

Why not just use the LLM for everything? Cost and latency, but mostly determinism. Regex either matches or it doesn't; you want the probabilistic component to be the fallback, not the front door.

Where this slots in

OTP extraction is rarely the whole feature — it's the middle step of something bigger, usually an agent signing up for a third-party service end to end: provision the mailbox, submit the form, catch the verification, finish onboarding. The link-based variant of verification is the same architecture with a URL regex instead of a digit regex.

Try this with a service you control first: point a test signup at the agent's address, watch the webhook land, and check which of the three regex tiers actually matched. If you've built OTP extraction before — what's the weirdest code format you've had to parse? I'm collecting nominations.

Ephemeral Inboxes: Spin Up a Mailbox Per Test Run

Qasim Muhammad — Fri, 12 Jun 2026 00:53:10 +0000

Two CI workers kick off at the same moment. Both sign up a test user, both poll the shared QA Gmail account for "the" verification email, and worker #7 grabs the message that belonged to worker #12. The test passes. The wrong test. You spend an afternoon staring at a green build that should've been red.

Shared inboxes are the single biggest source of flakiness in email-dependent E2E tests, and every workaround — catch-all forwarding rules, label rules scoped per PR, OAuth tokens living on the runner — adds another moving part that breaks on its own schedule. The fix is structural: every test gets its own address, on infrastructure your suite provisions and destroys.

One wildcard, infinite addresses

The E2E email testing recipe sets this up with one CLI command:

nylas inbound create e2e

You get back an inbox ID and a wildcard pattern shaped like e2e-*@yourapp.nylas.email. From there, each test mints a unique address under the wildcard — e2e-<uuid>@yourapp.nylas.email — and there's nothing to provision per address. You don't pay or configure per address either; the wildcard is just a convention, so burn UUIDs freely. Mail flows through MX records hosted on the Nylas side, which means zero DNS work in your own zone (the tradeoff: addresses live under *.nylas.email).

The Playwright fixture is two pieces — an address minter and a poller:

export const test = base.extend<Fixtures>({
  testEmail: async ({}, use) => {
    await use(`e2e-${randomUUID()}@yourapp.nylas.email`);
  },

  pollInbox: async ({ testEmail }, use) => {
    const poll = async (timeoutMs = 30_000) => {
      const deadline = Date.now() + timeoutMs;
      while (Date.now() < deadline) {
        const out = execSync(
          `nylas inbound messages ${process.env.INBOX_ID} --json --limit 50`,
        ).toString();
        const match = JSON.parse(out).find((m) =>
          m.to.some((t) => t.email === testEmail),
        );
        if (match) return match;
        await new Promise((r) => setTimeout(r, 1500));
      }
      throw new Error(`Email never arrived for ${testEmail}`);
    };
    await use(poll);
  },
});

A signup test then reads the way you wish it always had:

test("signup completes after email verification", async ({ page, testEmail, pollInbox }) => {
  await page.goto("/signup");
  await page.getByLabel("Email").fill(testEmail);
  await page.getByLabel("Password").fill("hunter2-correct");
  await page.getByRole("button", { name: "Create account" }).click();

  await expect(page.getByText("Check your inbox")).toBeVisible();

  const msg = await pollInbox();
  const linkMatch = msg.body.match(/https:\/\/[^\s"<]+\/verify\?[^\s"<]+/);
  expect(linkMatch).not.toBeNull();

  await page.goto(linkMatch![0]);
  await expect(page.getByText("Email verified")).toBeVisible();
});

Password reset is the same shape. OTP flows swap the link regex for /\b\d{6}\b/ — though watch out for bodies with multiple 6-digit numbers (phone numbers, transaction IDs); match near the label text or use a stricter extraction helper. And when the verification URL lives in an <a href> instead of plain text, parse the HTML rather than regexing the whole body:

import * as cheerio from "cheerio";

const $ = cheerio.load(msg.html);
const link = $('a:contains("Verify your email")').attr("href");

Why this is parallel-safe by construction

Playwright runs tests across workers, and with fullyParallel: true the inbox ID is shared — but the addresses aren't. Each test polls for messages addressed to its UUID, so the matching logic never sees another worker's mail. No filtering by subject, no "wait until the right message bubbles to the top." Delivery latency is typically under 5 seconds, so the 1.5-second poll interval catches most messages within two iterations; the 30-second default timeout is generous for almost any flow.

One performance note from the recipe: execSync blocks the test until the CLI returns. That's fine for most suites, but chatty ones should swap in execAsync and await in parallel. And if you want a clean inbox between debugging sessions, mark messages read in an afterEach — otherwise mail just ages out with the standard retention window.

When the test needs a full mailbox, not just an address

A wildcard inbox covers assertion-style tests: did the email arrive, does it contain the right link. Some suites need more — an identity that can send, sign up for a third-party service, and complete onboarding autonomously. That's the Agent Account flow: a fully functional, API-controlled mailbox (Agent Accounts are in beta) that your pipeline provisions per run.

nylas agent account create signup-agent@agents.yourdomain.com

The recipe pairs this with a message.created webhook, which fires within a second or two of mail arriving — your handler matches the expected sender, fetches the full body, extracts the confirmation link, and follows it. Two of its warnings are worth tattooing onto any test-infra design doc:

Don't trust the first message that arrives. Plenty of services send a "Welcome" email before the verification email. Match the sender and the expected URL pattern before acting on anything.
Don't ship per-run agents without teardown. Inactive grants accumulate. Delete on completion or failure:

nylas agent account delete signup-agent@agents.yourdomain.com --yes

Also practical: a free-plan Agent Account sends up to 200 messages per account per day, so a large test matrix should provision multiple grants rather than hammering one. If your test address ever leaks, an allow-list policy — a list of allowed from.domain values paired with a block rule for everything else — keeps the inbox deterministic. And one non-technical warning the recipe makes explicitly: programmatic signup is fine for your own testing and first-party integrations, but check the target service's terms before automating against third parties.

Which one do you need?

Rough decision rule: if the test only ever receives (verification links, OTPs, notification assertions), the wildcard inbound inbox is lighter and faster to adopt. If the test has to act — send replies, complete a signup conversation, exercise your product's email round-trip — provision an Agent Account per run and tear it down in afterAll.

A reasonable middle ground is reusing one long-lived Agent Account across signup runs instead of provisioning per run — the signup recipe explicitly supports both. Per-run accounts give you perfect isolation; a reused account gives you faster setup and one less teardown path to get wrong. Pick per-run for parallel CI, reused for local development.

The proof-of-concept costs about ten minutes: run nylas inbound create e2e, drop the fixture above into your Playwright project, and convert exactly one flaky signup test. Run it with --repeat-each=10 next to the old shared-inbox version and compare failure counts. That diff is the whole argument.

Give Your Scheduling Bot Its Own Calendar

Qasim Muhammad — Fri, 12 Jun 2026 00:53:06 +0000

A scheduling link makes the human do the work; a scheduling agent with its own calendar does the negotiating. Booking pages outsource the back-and-forth to a UI. The agent model keeps it where it already happens — in email — and answers from a real address with a real calendar behind it.

The setup: meeting requests land at scheduling@agents.yourcompany.com, an LLM parses intent, the agent checks availability against its own free/busy, proposes slots, and creates events that show up as normal invitations in Google Calendar, Microsoft 365, and Apple Calendar. No human mailbox in the loop, no delegation permissions, no calendar borrowed from whoever set the bot up.

This runs on a Nylas Agent Account — a hosted mailbox-plus-calendar you provision through the API. Agent Accounts are in beta, so expect some movement before GA.

Provision the identity

One CLI command or one API call:

nylas agent account create scheduling@agents.yourcompany.com

The primary calendar is provisioned automatically — no extra call before you can create events on it. The API equivalent is POST /v3/connect/custom with "provider": "nylas" and the email address in settings; no OAuth refresh token involved. Save the grant ID, then subscribe a webhook to four triggers: message.created, event.created, event.updated, and event.deleted. When Nylas sends the challenge GET to your endpoint, respond with the challenge value within 10 seconds to activate it.

The negotiation loop

The full tutorial wires this end to end, but the shape is:

Human emails the agent. message.created fires; the webhook only carries summary fields, so the handler fetches the full body.
The LLM extracts duration, timezone, and urgency.
The agent queries /calendars/free-busy against its own primary calendar and replies with 3 candidate slots.
The human picks one; another message.created fires; the agent creates the event with notify_participants=true.

The availability check is the part people overcomplicate. Free/busy returns busy blocks over a window; the agent generates candidate slots and filters out the overlaps:

const freeBusy = await nylas.calendars.getFreeBusy({
  identifier: AGENT_GRANT_ID,
  requestBody: {
    startTime: Math.floor(parsed.preferredWindow.start.getTime() / 1000),
    endTime: Math.floor(parsed.preferredWindow.end.getTime() / 1000),
    emails: ["scheduling@agents.yourcompany.com"],
  },
});

const openSlots = candidates.filter(
  (slot) => !overlapsAnyBusyBlock(slot, freeBusy.data),
);

The proposal reply then goes out through the standard send endpoint with replyToMessageId set, so it threads under the original request. The recipient sees a normal reply from the agent's address — no relay footer, no sent-via branding.

That last flag matters. With notify_participants=true, an ICS REQUEST goes out from the agent's address, and the recipient's calendar client renders it as a standard invitation:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary&notify_participants=true" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Product demo",
    "when": { "start_time": 1744387200, "end_time": 1744390800 },
    "participants": [
      { "email": "alice@example.com" },
      { "email": "bob@example.com" }
    ]
  }'

When Alice clicks Yes in Gmail, Google sends the response back to the agent's mailbox, the event's participants[].status updates automatically, and event.updated fires — the agent knows who accepted without parsing a single email. Declines can trigger an LLM-drafted "here are some alternatives" reply; reschedule proposals can be answered with POST /events/{id}/send-rsvp and a status of yes, no, or maybe, which goes out as a standard ICS REPLY every participant sees.

Updates, cancellations, and the notify switch

notify_participants is a per-call decision, not a one-time setting, and it applies to the whole event lifecycle. A PUT /events/{id} with changed fields updates the meeting on every participant's calendar; DELETE /events/{id} removes it everywhere. Pass notify_participants=false when you want silence — pre-staging events the agent will announce later, or backfilling historical data without emailing anyone.

The trap is the inverse: deleting an event without notify_participants=true leaves the meeting sitting on participants' calendars. For a scheduling agent, cancel with notification unless you have a specific reason not to. One more timezone note from the calendars doc: an Agent Account has no default time zone the way a human's calendar does, so pass timezone on create or stick to epoch start_time/end_time.

The agent as invitee, not just organizer

It works in reverse too. When someone invites the agent to their meeting, the invitation flows through the mailbox, Nylas parses it, and a matching event appears on the agent's primary calendar with the agent's status set to noreply. You drive the response logic entirely off the event.created webhook — the event object already carries the organizer, participants, and times. One gotcha from the calendars doc: the invite email also fires message.created, so decide which webhook drives your logic and ignore the other, or you'll process every invitation twice.

Field notes worth stealing

A few things the tutorial calls out that are easy to learn the hard way:

Threading is testable — test it. Replies must preserve Message-ID, In-Reply-To, and References so the conversation threads in Gmail and Outlook. Nylas preserves these on outbound; send yourself a request and verify the reply lands in the original thread before launch.
Watch the send cap. Free-plan Agent Accounts send up to 200 messages per account per day, and a busy scheduling agent — proposals, confirmations, reminders — can get there. Paid plans have no daily cap by default; a policy can also set a stricter quota. Sort this before launch, not after the first missed confirmation.
Don't tunnel through ngrok. Nylas blocks webhook URLs on ngrok because of throughput limiting; use VS Code port forwarding or Hookdeck for local development.
Humans can supervise over IMAP. Set app_password on the grant and your ops team can open the agent's mailbox in Outlook or Apple Mail to audit replies and intervene — every IMAP action syncs back to the API.
Separate calendars for separate concerns. Beyond the primary, you can create additional calendars up to your plan's cap — say, sales-calls and internal on the same agent.
The agent can't see mail it never receives. A request routed to junk won't fire a message.created on the inbox. If you run spam rules, audit them with the rule evaluations endpoint so important senders aren't silently filtered.
Wrong parses create real calendar chaos. Latency is forgiving here (minutes, not milliseconds), but intent extraction errors are not. Require human confirmation for first-time senders or high-value meetings.
One agent per role. Scheduling, support, and outreach want different quotas and spam sensitivities. Model each as its own account with its own policy.

Counter-proposing a time isn't a first-class endpoint today — the common pattern is RSVP no or maybe plus a reply proposing alternatives. For heavily negotiated multi-participant flows, Scheduler is purpose-built and works with Agent Accounts.

If you want to try this, the fastest start is a trial *.nylas.email subdomain: provision the account, create one event with notify_participants=true, and accept it from your personal calendar. Watching event.updated arrive the moment you click Yes is the point where the architecture clicks. What's your tolerance for letting the LLM book without human confirmation — and where would you draw that line?

A Sales Outreach Agent That Owns Its Email Address

Qasim Muhammad — Fri, 12 Jun 2026 00:53:01 +0000

200 messages per account per day. That's the free-plan send ceiling on a Nylas Agent Account, and it's a surprisingly useful number to design an outreach agent around — it forces the kind of pacing that keeps cold email from becoming spam, and paid plans drop the daily cap by default when you outgrow it.

The bigger idea: instead of sending campaigns through a rep's mailbox or a send-only API, the agent gets its own address. sales-agent@yourcompany.com is a real mailbox — it sends, it receives replies, it owns a calendar. Agent Accounts are in beta, but the model is straightforward: each account is just another grant, so the Messages, Threads, Events, and Webhooks endpoints you'd use for a connected Gmail account work unchanged.

What the loop looks like

The sales-outreach pattern from the product docs runs in three stages, all on one grant_id:

Send the campaign through the standard send endpoint.
Classify replies with an LLM into interested / not now / unsubscribe, threading every exchange through the Messages API.
Book the meeting — when a prospect says yes, the same grant creates an event on the agent's own calendar and sends the invite.

No CRM hand-offs between three tools, no rep mailbox cluttered with sequence noise.

Replies arrive as webhooks

Inbound mail fires message.created, and the payload looks exactly like it does for any other grant. One subscription covers your whole application:

curl --request POST \
  --url 'https://api.us.nylas.com/v3/webhooks/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data-raw '{
    "trigger_types": ["message.created", "event.created", "event.updated"],
    "description": "Outreach agent",
    "webhook_url": "https://your-app.example.com/webhooks/nylas",
    "notification_email_addresses": ["dev-team@your-company.com"]
  }'

Your endpoint gets a GET with a challenge query parameter first — echo it back in a 200 and deliveries start flowing as POSTs. The payload's data.object carries sender, recipients, subject, snippet, and the field that matters most here: thread_id, which groups the whole back-and-forth into one conversation your classifier (and your CRM) can reason about.

Two handler habits from the pipeline recipe are worth copying verbatim. First, respond with a 200 immediately and do the real work after — slow handlers trigger Nylas retries, which means more duplicates to dedup. Second, verify the signature before trusting anything in the body:

const crypto = require("crypto");

function verifyWebhookSignature(req, webhookSecret) {
  const signature = req.headers["x-nylas-signature"];
  const hmac = crypto.createHmac("sha256", webhookSecret);
  const digest = hmac.update(JSON.stringify(req.body)).digest("hex");
  return signature === digest;
}

An outreach agent acts on what webhooks tell it. A forged message.created that skips verification is a forged instruction to your agent.

The unglamorous parts that decide whether this works

The sales pipeline automation recipe is blunt about where these systems fail, and every lesson transfers directly to an outreach agent:

Webhooks are at-least-once. The same message.created notification can land twice, especially if your handler was slow. Track processed webhook IDs in Redis or a database table with a TTL — an in-memory Set doesn't survive restarts. An outreach agent that double-processes a reply is an agent that replies twice.

Out-of-office replies fire message.created like real replies. Detect them with subject patterns (out of office, automatic reply, auto-reply) and skip. An OOO classified as "interested" pollutes your pipeline worse than a missed reply.

Use the folders field for direction. A message in SENT is the agent's own outbound; INBOX means the prospect wrote back. Don't compare addresses against a roster — check the folder.

Skip internal mail. If every address on a message belongs to one of your company's domains, it's colleagues talking — not pipeline signal. Compare sender and recipient domains against your own and bail early, or your activity log fills up with "lunch?" threads.

Filter automated senders. no-reply@, notifications@, mailer-daemon@, postmaster@, bounce@ — none of these are prospects, and a bounce treated as engagement is how an agent emails a dead address forever. The recipe also flags the List-Unsubscribe header and "unsubscribe" in the subject as bulk-sender tells.

const noReplyPatterns = [
  /^no-?reply@/i,
  /^notifications?@/i,
  /^mailer-daemon@/i,
  /^postmaster@/i,
  /^bounce@/i,
];
if (noReplyPatterns.some((p) => p.test(senderEmail))) return;

Closing the loop on the calendar

This is the piece send-only infrastructure can't replicate. When the classifier returns interested and the prospect agrees to a time, the agent creates the event on its own primary calendar with notify_participants=true. The invite goes out from the agent's address as a normal calendar invitation; the event.created and event.updated webhooks in the subscription above tell you when the prospect accepts. The same recipe's advice applies here too: key CRM records on the event id, because meetings get rescheduled constantly and event.updated will fire for every change.

For longer deal cycles, replies can arrive days after the last touch. The multi-turn conversation pattern — send, receive, restore context from the thread, respond — is built for exactly that, and the thread history doubles as the record of everything the agent ever told a prospect.

Why not just use the rep's inbox?

You can connect rep mailboxes over OAuth, and for logging human activity into a CRM that's the right call — the pipeline recipe does precisely that with message.created and event.created across connected grants. But campaign sends from a rep's address mean the rep's sender reputation absorbs the campaign's bounces, the rep's inbox absorbs the replies, and offboarding the rep breaks the integration. A dedicated agent identity isolates all three. You can even provision one agent per customer domain — sales-agent@customer-a.com, sales-agent@customer-b.com — each with its own quota and reputation, all in one application.

Quick answers

Do I need one webhook per agent? No — a single subscription covers every grant in your Nylas application, agents and connected rep accounts alike. Branch on the grant's provider ("nylas") to tell agent deliveries apart from connected-grant deliveries.

What about contact data? Reply classification gets you intent; the pipeline recipe pairs it with a nightly job that pulls contacts from the Contacts API (paginated 50 at a time with next_cursor) and patches fresh phone numbers, job titles, and companies into the CRM. Real-time webhooks for activity, periodic sync for data that rots slowly.

If you want to test the shape of this without committing, provision an account on a trial *.nylas.email domain, point the webhook at a tunnel, and run a five-prospect campaign against your own test addresses. The classification step is where the interesting tuning lives — what label set are you using for reply intent? I'd genuinely like to hear what taxonomies are working for people in the comments.

Build an Email Support Triage Agent With Its Own Inbox

Qasim Muhammad — Fri, 12 Jun 2026 00:52:55 +0000

Every shared support inbox eventually becomes a triage problem: 80 unread messages, no agreement on what "urgent" means, and the one person who knows which customer is about to churn is on PTO. Teams keep solving this with labels and heroics. It's a better fit for an LLM — as long as the LLM has somewhere safe to live.

That's the case for giving the triage agent its own mailbox. Nylas Agent Accounts (currently in beta) are hosted mailboxes you create entirely through the API. A support@yourcompany.com Agent Account receives every inbound support email, gets six system folders out of the box (inbox, sent, drafts, trash, junk, archive), and exposes the same grant_id-based endpoints as any connected Gmail or Outlook account.

Creating one is a single request:

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",
    "settings": { "email": "support@yourcompany.com" }
  }'

Save the grant_id from the response — every other call hangs off it.

Four buckets beat five

The classification scheme from the email triage agent recipe sorts mail into exactly four categories:

Bucket	Meaning	Action
`URGENT`	Production incident, executive ask	Draft a reply within the hour
`ACTION`	Code review, meeting follow-up	Draft a reply same-day
`FYI`	Status update	Leave it alone
`NOISE`	Newsletter, automated alert	Archive

Four is deliberate. Three loses fidelity — everything collapses into "important." Five and the model starts confusing adjacent categories.

The prompt runs with temperature=0 and max_tokens=10, and the model only sees sender + subject + a 200-character snippet, not the full body. That's enough for over 90% accuracy. Here's the prompt verbatim from the recipe:

You triage email into one of four categories:

URGENT  — production incidents, executive requests; reply within 1 hour
ACTION  — code reviews, meeting follow-ups; reply same day
FYI     — informational, no response needed
NOISE   — newsletters, marketing, automated notifications

From:    {sender}
Subject: {subject}
Snippet: {snippet}

Return ONLY the category name. Nothing else.

Validate the output against the four valid strings (LLMs occasionally invent a category) and fall back to FYI on anything unrecognized.

The cost math is almost a rounding error. GPT-4o-mini runs about $0.15 per million input tokens; a 200-character snippet plus the prompt is roughly 150 tokens, so 100 emails is about 15K tokens — call it $0.002. Drafting uses a stronger model (GPT-4o, around $2.50 per million input tokens), but only on the URGENT and ACTION subset, typically under 20% of the inbox. A heavy day at 200 unread emails costs roughly a nickel. And if some of that mail can't leave your infrastructure, point the same OpenAI client at a local Ollama endpoint — Llama 3.1 classifies almost as well as GPT-4o-mini for this task, though drafting quality drops noticeably below a 70B-parameter model.

Drafting is where you add a second gate

Classifying wrong is cheap. Replying wrong is expensive. The support agent pattern layers two independent checks before any draft exists:

Confidence gating on the knowledge-base match. At a score of 0.85 or higher, draft directly from the matched article. Between 0.60 and 0.85, draft conservatively and cite the article inline so a reviewer can verify. Below 0.60, don't draft at all — flag for manual handling with the best-guess article attached.

Risk tiering, which doesn't care about confidence. Password resets and FAQ-shaped questions get drafted. Refunds and billing changes get drafted with extra scrutiny. Legal threats, regulatory matters, and fraud reports skip the model entirely and escalate to a human with full context. A high-confidence KB match for a refund question still goes through review — the Air Canada chatbot ruling is the canonical reminder of why.

In both recipes, the agent never hits send. Drafts land in the drafts folder; a human approves. On an Agent Account that drafts folder belongs to the agent itself, so the review queue and the audit trail are the same mailbox.

def handle(msg):
    question = extract_question(msg)
    article, conf = kb.search(question)

    if classify_risk(msg) == "high":
        escalate_to_human(msg, reason="high-risk topic")
        return

    if conf < 0.60:
        flag_for_review(msg, article)
        return

    draft = generate_draft(msg, article, cite_inline=(conf < 0.85))
    queue_for_approval(msg, draft, article)

Rules filter before the model ever runs

Here's the part a borrowed human inbox can't do. Agent Accounts support inbound rules that run at the mail layer: block known spam domains at the SMTP stage, auto-route invoices to a finance folder with assign_to_folder, mark VIP senders for immediate attention. The junk never reaches your classification prompt, which also means injection-laden garbage never enters the model's context. Rules and allow/block lists are covered in the Agent Accounts overview.

Inbound mail fires the standard message.created webhook — identical in shape to the same event for any other grant — so the trigger side of your pipeline is whatever you already run for connected accounts. If webhooks are more infrastructure than you want on day one, polling works; the support recipe suggests every 5–15 minutes, which is fine latency for support.

Rollout advice from the recipes

Start at 5 tickets per cycle while you tune the KB matcher and risk classifier. Bump to 20 once the false-positive rate is acceptable.
Group similar tickets. If the agent sees three "where's my receipt?" tickets in a row, batch them — same KB article, same draft template, one reviewer pass.
Track what the agent can't match. Low-confidence tickets are the strongest signal of where your knowledge base has holes.
Mind the send cap. A free-plan Agent Account sends up to 200 messages per account per day; paid plans have no daily cap by default, and a policy can set a stricter quota.
Cap reply length in the prompt. The drafting prompt in the triage recipe says "three sentences max," and that constraint is load-bearing — without it, drafts read like a politely overcompensating intern.
Log everything — every classification, KB lookup, and approval decision — to your own store. Support is the workload where you'll be asked "why did it say that?" months later.

The cheapest way to evaluate this is to run classification-only for a week: create the Agent Account, point a copy of your support flow at it, and log the four-bucket output without drafting anything. Compare against what your humans actually prioritized. If the agreement rate clears 90%, you've earned the right to turn on drafting.

Give Your AI Agent Its Own Email Address (Not Access to Yours)

Qasim Muhammad — Fri, 12 Jun 2026 00:52:40 +0000

Most "AI agent + email" tutorials start the same way: connect the agent to a human's inbox over OAuth, hope the token doesn't expire mid-run, and pray the agent never replies to the wrong thread on someone's behalf.

There's a different model: give the agent its own email address. Nylas recently shipped Agent Accounts (currently in beta) — fully functional, Nylas-hosted mailboxes you create and control entirely through the API. Each one is a real name@company.com address that sends, receives, hosts calendar events, and RSVPs to invitations. To anyone interacting with it, it's indistinguishable from a human-operated account.

I work on the docs at Nylas, so I've spent a lot of time with this API. Here's a tour of what it does and how to get a mailbox running in a few minutes.

Why not just connect the agent to a human inbox?

You can — that's what OAuth grants are for, and they're the right tool when the agent works on behalf of a person. But a lot of agent workflows want a first-class identity instead:

System mailboxes (sales@, support@, scheduling@) that your app owns end-to-end. No OAuth consent screen, no user offboarding breaking your integration.
Ephemeral inboxes for test automation — provision a fresh address per run, sign up for a service, grab the OTP from the verification email, tear it down.
Per-customer identities in multi-tenant apps: scheduling@customer-a.com, scheduling@customer-b.com, each with its own send quota and sender reputation, all in one Nylas application.
A scheduling bot with its own calendar that proposes slots, sends invites, and shows up as a normal participant in Google Calendar, Microsoft 365, and Apple Calendar.

The key design decision: 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. If you've already built against connected accounts, nothing new to learn.

Create a mailbox with one API call

Every Agent Account lives on a domain — either a Nylas-provided *.nylas.email trial subdomain (instant, good for testing) or your own domain with MX and TXT records configured. With a domain registered, creation is a single request to the same Bring Your Own Auth endpoint Nylas uses for other providers, with "provider": "nylas". No refresh token needed:

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",
    "settings": {
      "email": "test@your-application.nylas.email"
    }
  }'

The response contains a grant_id — save it, it's the handle for everything else. The mailbox is live immediately with six system folders (inbox, sent, drafts, trash, junk, archive) and a primary calendar.

If you prefer a CLI, it's one command after nylas init:

nylas agent account create test@your-application.nylas.email

Receive email like any other grant

Inbound mail fires the standard message.created webhook — identical in shape to the same event for a Gmail or Outlook grant. Register one and Nylas calls your URL the moment a message arrives:

curl --request POST \
  --url "https://api.us.nylas.com/v3/webhooks" \
  --header "Authorization: Bearer $NYLAS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "trigger_types": ["message.created"],
    "callback_url": "https://yourapp.example.com/webhooks/nylas"
  }'

If your app handles both connected grants and Agent Accounts, branch on the grant's provider field ("nylas") to tell the deliveries apart. Polling GET /v3/grants/{grant_id}/messages works too if you don't want webhook infrastructure yet.

Send from the agent's own address

Outbound mail uses the same send endpoint as any connected grant:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/$GRANT_ID/messages/send" \
  --header "Authorization: Bearer $NYLAS_API_KEY" \
  --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. Replies land back in the agent's inbox and thread normally, so multi-turn conversations (the thing LLM agents are actually good at) work out of the box.

The calendar is real too

Every Agent Account ships with a primary calendar that speaks standard iCalendar/ICS. The agent can:

create events and invite people (POST /v3/grants/{grant_id}/events)
accept or decline invitations it receives (POST /v3/grants/{grant_id}/events/{id}/send-rsvp)

Because it's plain ICS under the hood, every major calendar client treats the agent as a regular participant. A scheduling agent can own its availability instead of borrowing a human's.

Guardrails: policies, rules, and lists

Letting an autonomous agent send email is exactly the kind of thing that deserves guardrails, and this is where Agent Accounts get interesting. You can attach policies that bundle send limits, spam detection, attachment restrictions, and retention settings — and assign one policy to many accounts. Rules match on sender, recipient, or message type and run actions like block, mark_as_spam, or assign_to_folder, with allow/block lists of domains, TLDs, or addresses referenced through an in_list operator.

So your support triage agent can block known spam domains at the SMTP stage before your LLM ever sees the message — which also keeps prompt-injection-laden junk out of the model's context.

Limits worth knowing (beta, free plan)

Send rate: 200 messages per account per day on the free plan (paid plans have no daily cap by default)
Storage: 3 GB per organization on the free plan
Retention: 30 days inbox, 7 days spam on the free plan (configurable via policy)
Outbound message size: 40 MB total
Domains: unlimited — one application can manage accounts across any number of registered domains

Agent Accounts are in beta, so the API may change before general availability.

Try it

The quickstart goes from zero to a sending-and-receiving mailbox in under 5 minutes. If you want recipes, the cookbook covers handling replies, multi-turn conversations, OTP extraction, and signing up for services autonomously.

Curious what people are building with agent-owned identities — if you've given an agent its own inbox (with Nylas or anything else), I'd love to hear how it went in the comments.

Manage Nylas Applications, Connectors, and Grants from the CLI

Qasim Muhammad — Mon, 11 May 2026 02:09:02 +0000

The nylas admin commands let you manage your Nylas infrastructure without the web dashboard. Create applications, configure provider connectors, manage OAuth credentials, and monitor grants — all from the terminal.

What nylas admin does

Full API management surface: applications, callback URIs, provider connectors (Google, Microsoft, IMAP), credentials, and grants. Useful for CI/CD pipelines, multi-tenant setups, and infrastructure-as-code workflows.

Quick Start

brew install nylas/nylas-cli/nylas
nylas init
nylas admin applications list

Key commands

Command	What it does
`nylas admin applications list`	List all applications
`nylas admin applications create`	Create a new application
`nylas admin connectors list`	List provider connectors
`nylas admin connectors create`	Create a Google/Microsoft/IMAP connector
`nylas admin credentials list <connector-id>`	List credentials for a connector
`nylas admin credentials create`	Add OAuth credentials
`nylas admin callback-uris list`	List OAuth callback URIs
`nylas admin callback-uris create --url <url>`	Register a new callback URI
`nylas admin grants list`	List all grants on the application
`nylas admin grants stats`	Show grant statistics

Creating an application and connector

# Create app
nylas admin applications create --name "prod-email" --json

# Add Google connector
nylas admin connectors create \
  --provider google \
  --client-id $GOOGLE_CLIENT_ID \
  --client-secret $GOOGLE_CLIENT_SECRET

# Register callback URI
nylas admin callback-uris create --url https://myapp.com/oauth/callback

Monitoring grants

# How many users are connected?
nylas admin grants stats --json

# List all grants with their status
nylas admin grants list --json | jq '.[] | {id, provider, status}'

All commands: Nylas CLI Command Reference

Get started: brew install nylas/nylas-cli/nylas — other install methods

Agent Policies and Rules — Control What Your AI Agent Can Send and Receive

Qasim Muhammad — Mon, 11 May 2026 02:08:56 +0000

The nylas agent policy and nylas agent rule commands define guardrails for AI agent email accounts. Set who the agent can email, what triggers are allowed, and what actions to take on inbound messages — all enforced server-side.

What policies and rules do

A policy is a named container for rules. Rules define conditions and actions: "if the sender is external, block" or "if sending to a non-internal domain, require approval." These fire before the agent sees the message, so prompt injection can't bypass them.

Quick Start

nylas agent policy create --name "production-guardrails" --json
nylas agent rule create \
  --name "internal-only-outbound" \
  --condition "recipient_domain != company.com" \
  --action block

Key commands

Command	What it does
`nylas agent policy list`	List all policies
`nylas agent policy create --name N`	Create a named policy
`nylas agent policy get <id>`	Show policy details
`nylas agent policy delete <id> --yes`	Delete a policy
`nylas agent rule list`	List all rules
`nylas agent rule create --name N --condition C --action A`	Create a rule from flags
`nylas agent rule create --data-file rule.json`	Create from JSON file
`nylas agent rule get <id>`	Show a rule
`nylas agent rule delete <id> --yes`	Delete a rule
`nylas agent account create <email> --policy-id <id>`	Attach policy to agent

Example: restrict outbound to internal domains only

# Create policy
POLICY=$(nylas agent policy create --name "internal-only" --json | jq -r '.id')

# Add rule: block any outbound to non-company domains
nylas agent rule create \
  --policy-id $POLICY \
  --name "block-external-send" \
  --condition "direction == outbound AND recipient_domain != mycompany.com" \
  --action block

# Attach to agent account
nylas agent account create agent@mycompany.nylas.email --policy-id $POLICY

Example: auto-archive marketing emails

nylas agent rule create \
  --name "archive-marketing" \
  --condition "sender_domain IN (marketing.example.com, promo.example.com)" \
  --action archive

All commands: Nylas CLI Command Reference

Get started: brew install nylas/nylas-cli/nylas — other install methods

Manage Email Signatures from the CLI — Create, List, and Attach to Sends

Qasim Muhammad — Mon, 11 May 2026 02:08:52 +0000

The nylas email signatures commands manage reusable email signatures stored per-grant. Create HTML signatures once, attach them to any send with a flag — no more pasting footers manually.

What email signatures do

Signatures are HTML blocks stored server-side and attached to outgoing emails via --signature-id. Create different signatures for different contexts (formal, casual, department) and switch between them per-send.

Quick Start

nylas email signatures create --name "Work" --body "<p>— Qasim<br>Staff SRE, Nylas</p>"
nylas email send --to alice@example.com --subject "Hello" --body "..." --signature-id SIG_ID

Key commands

Command	What it does
`nylas email signatures list`	List stored signatures
`nylas email signatures show <id>`	Show signature HTML
`nylas email signatures create --name N --body B`	Create from inline HTML
`nylas email signatures create --name N --body-file FILE`	Create from HTML file
`nylas email signatures update <id>`	Update a signature
`nylas email signatures delete <id> --yes`	Delete a signature

Creating a signature from a file

cat > sig.html << 'EOF'
<p style="font-family: sans-serif; font-size: 14px;">
  <strong>Qasim Muhammad</strong><br>
  Staff SRE · Nylas<br>
  <a href="https://cli.nylas.com">cli.nylas.com</a>
</p>
EOF

nylas email signatures create --name "Default" --body-file sig.html --json

Using a signature when sending

nylas email send \
  --to team@company.com \
  --subject "Weekly update" \
  --body "Here's the summary..." \
  --signature-id <sig-id>

The signature HTML is appended to the email body automatically.

All commands: Nylas CLI Command Reference

Get started: brew install nylas/nylas-cli/nylas — other install methods

DEV Community: Qasim Muhammad

One Agent Identity Per Customer: Multi-Tenant Email

The architecture in one paragraph

Domains: register once, mint accounts forever

Workspaces are the tenant boundary

Fleet operations without leaving the terminal

Quotas and the optional human door

Verifying a tenant is live

Two questions that come up in design reviews

Voice Agents That Follow Up by Email

The identity half

The plumbing half

Voice surfaces every UX mistake immediately

Why the dedicated address changes the product

Quick answers

How an AI Agent Can Sign Up for a Service on Its Own

Provision, subscribe, sign up

Catch the verification email

The judgment calls the code doesn't show

Why this pattern is bigger than signups

Extract OTP Codes From Email, Automatically

Step one: make sure it's the right email

Regex first, LLM second

Getting the code back to whoever's waiting

The failure modes that actually bite

Quick answers

Where this slots in

Ephemeral Inboxes: Spin Up a Mailbox Per Test Run

One wildcard, infinite addresses

Why this is parallel-safe by construction

When the test needs a full mailbox, not just an address

Which one do you need?

Give Your Scheduling Bot Its Own Calendar

Provision the identity

The negotiation loop

Updates, cancellations, and the notify switch

The agent as invitee, not just organizer

Field notes worth stealing

A Sales Outreach Agent That Owns Its Email Address

What the loop looks like

Replies arrive as webhooks

The unglamorous parts that decide whether this works

Closing the loop on the calendar

Why not just use the rep's inbox?

Quick answers

Build an Email Support Triage Agent With Its Own Inbox

Four buckets beat five

Drafting is where you add a second gate

Rules filter before the model ever runs

Rollout advice from the recipes

Give Your AI Agent Its Own Email Address (Not Access to Yours)

Why not just connect the agent to a human inbox?

Create a mailbox with one API call

Receive email like any other grant

Send from the agent's own address

The calendar is real too

Guardrails: policies, rules, and lists

Limits worth knowing (beta, free plan)

Try it

Manage Nylas Applications, Connectors, and Grants from the CLI

What nylas admin does

Quick Start

Key commands

Creating an application and connector

Monitoring grants

Related posts

Agent Policies and Rules — Control What Your AI Agent Can Send and Receive

What policies and rules do

Quick Start

Key commands

Example: restrict outbound to internal domains only

Example: auto-archive marketing emails

Related posts

Manage Email Signatures from the CLI — Create, List, and Attach to Sends

What email signatures do

Quick Start

Key commands

Creating a signature from a file

Using a signature when sending

Related posts