Provisioning a working email mailbox from Node.js takes less code than the average OAuth callback handler. No consent screen, no token refresh job, no provider SDK — one fetch call returns a grant ID, and from there the mailbox sends, receives, and RSVPs to calendar invites. That's the pitch for Nylas Agent Accounts, hosted email-and-calendar identities you control entirely through the API. They're in beta, and the official quickstart promises a working account in under 5 minutes. The docs show it in curl; here's the same flow in JavaScript.
What you need
Two things: an API key, and a registered domain for the mailbox to live on. For testing, the zero-DNS path is a *.nylas.email trial subdomain registered from the Dashboard — addresses like [email protected] work immediately. For production you'd register your own domain (the Dashboard generates the MX and TXT records to publish, and verification is automatic once they propagate), but the trial domain is fine for this walkthrough.
export NYLAS_API_KEY="nyk_..."
Create the mailbox
The endpoint is POST /v3/connect/custom — the same Bring Your Own Auth route used for other providers — with "provider": "nylas". Unlike OAuth providers, there's no refresh token in the body; just the address:
const BASE = "https://api.us.nylas.com";
const headers = {
Authorization: `Bearer ${process.env.NYLAS_API_KEY}`,
"Content-Type": "application/json",
};
const res = await fetch(`${BASE}/v3/connect/custom`, {
method: "POST",
headers,
body: JSON.stringify({
provider: "nylas",
settings: { email: "[email protected]" },
}),
});
const { data } = await res.json();
const grantId = data.id; // save this — every later call needs it
That grantId is the whole handle. The mailbox behind it is live as soon as the response comes back, and it works with every existing endpoint — messages, drafts, folders, calendars, events, webhooks.
One optional field deserves a mention even in a quickstart: workspace_id. Policies and rules (send quotas, spam settings, inbound filters) apply through workspaces, and passing a top-level workspace_id at creation places the account in one immediately:
body: JSON.stringify({
provider: "nylas",
workspace_id: process.env.NYLAS_WORKSPACE_ID,
settings: { email: "[email protected]" },
}),
Omit it and the account lands in your application's default workspace — fine for this walkthrough, worth being deliberate about in production.
Catch inbound mail
Two options, and the quickstart documents both. Polling is the simplest — list the inbox whenever you like:
const inbox = await fetch(
`${BASE}/v3/grants/${grantId}/messages?limit=5`,
{ headers },
).then((r) => r.json());
for (const msg of inbox.data) {
console.log(msg.subject, "—", msg.snippet);
}
The list call returns snippets; when the agent needs the full body — say, to hand it to an LLM — fetch the individual message:
const message = await fetch(
`${BASE}/v3/grants/${grantId}/messages/${messageId}`,
{ headers },
).then((r) => r.json());
console.log(message.data.body); // full HTML body
For real-time delivery, register a message.created webhook and the platform calls your URL the moment mail arrives:
await fetch(`${BASE}/v3/webhooks`, {
method: "POST",
headers,
body: JSON.stringify({
trigger_types: ["message.created"],
callback_url: "https://yourapp.example.com/webhooks/nylas",
}),
});
The receiving side is a plain HTTP handler. The payload's interesting bits live at data.object:
import express from "express";
const app = express();
app.use(express.json());
app.post("/webhooks/nylas", (req, res) => {
const msg = req.body?.data?.object;
if (req.body?.type === "message.created" && msg) {
console.log(`New mail for grant ${msg.grant_id}: ${msg.subject}`);
console.log(`From: ${msg.from?.[0]?.email} — ${msg.snippet}`);
}
res.sendStatus(200);
});
app.listen(3000);
The payload shape is identical to message.created for any other grant. If your app also handles connected Gmail or Outlook grants, branch on the grant's provider field — agent grants report "nylas".
One more inbound detail: attachments. IDs arrive on the message object, and the bytes stream from the download endpoint:
const bytes = await fetch(
`${BASE}/v3/grants/${grantId}/attachments/${attachmentId}/download?message_id=${messageId}`,
{ headers },
).then((r) => r.arrayBuffer());
Send a reply
Outbound uses the same send endpoint as any connected grant:
await fetch(`${BASE}/v3/grants/${grantId}/messages/send`, {
method: "POST",
headers,
body: JSON.stringify({
subject: "Hello from my Agent Account",
body: "This message was sent by a Nylas Agent Account.",
to: [{ email: "[email protected]", name: "You" }],
}),
});
The recipient sees a normal message from the agent's address — per the docs, no "sent via" branding and no relay footer.
Prefer the terminal for setup?
Everything in the provisioning half has a CLI equivalent if you'd rather keep Node for the application logic only. After nylas init (which creates the account and API key in one command):
# Create the mailbox
nylas agent account create test@your-application.nylas.email
# Confirm the connector is ready, list what exists
nylas agent status
nylas agent account list
# Register the webhook
nylas webhook create \
--url https://yourapp.example.com/webhooks/nylas \
--triggers message.created
The CLI prints the grant ID on create, and agent mailboxes show up in nylas auth list alongside any connected grants. A common split: CLI for one-time setup, the fetch calls above for everything your app does at runtime.
Run the loop end to end
The quickstart's own verification sequence, now fully scriptable:
- Send a mail from any client — Gmail, your phone — to the agent's address.
- Watch it arrive, either in your Express handler or via the polling snippet.
- Reply from Node with the send call above and confirm it lands back in your client.
Bonus round: the calendar
There's a calendar half to this story too. The account ships with a primary calendar, and the same grantId drives it. Creating an event with notify_participants=true sends real invitations from the agent's address:
await fetch(
`${BASE}/v3/grants/${grantId}/events?calendar_id=primary¬ify_participants=true`,
{
method: "POST",
headers,
body: JSON.stringify({
title: "Product demo",
when: { start_time: 1744387200, end_time: 1744390800 },
participants: [{ email: "[email protected]" }],
}),
},
);
And when someone invites the agent to a meeting, it answers with the send-rsvp endpoint — status is "yes", "no", or "maybe":
await fetch(
`${BASE}/v3/grants/${grantId}/events/${eventId}/send-rsvp?calendar_id=primary`,
{ method: "POST", headers, body: JSON.stringify({ status: "yes" }) },
);
Invitations travel over standard iCalendar/ICS, so Google Calendar, Microsoft 365, and Apple Calendar all treat the agent as a normal participant — the RSVP shows up for every attendee. Still, the mail loop above is the core of most agent use cases.
From here, the natural upgrade is putting an LLM between steps 2 and 3: webhook fires, model reads the message, send call delivers the drafted reply. Spin up a trial-domain account tonight and time yourself against the docs' 5-minute claim — then tell me in the comments what you'd build once your code has its own email address.
SOCIAL SHARE CARD GENERATOR