Guide

Manage Virtual Calendars from the CLI

A conference room doesn't have a Gmail login, and a borrowed projector doesn't have an Outlook mailbox. Virtual calendars give those resources a bookable schedule with no connected account. This guide creates, lists, inspects, and deletes them, then books events against them from the terminal.

Written by Aaron de Mello Senior Engineering Manager

Reviewed by Qasim Muhammad

Verified — CLI 3.1.17 · Nylas Virtual Calendars · last tested June 9, 2026

What is a virtual calendar?

A virtual calendar is a Nylas-hosted calendar that belongs to no third-party provider account. It carries no Google or Microsoft login and no synced mailbox, yet it accepts events and reports free/busy exactly like a real calendar. That makes it the right home for a conference room, a loaner laptop, or an external contractor who never connects an inbox.

Each virtual calendar is created as its own grant, so it gets a stable grant ID you address in later commands. The --email you pass is an identifier, not a real address — nothing is delivered to it. The Nylas v3 docs describe these as a way to schedule against resources without an underlying provider, which removes the need to provision a shared mailbox per room. One CLI call replaces an admin ticket that often takes a day to clear.

How do I create a virtual calendar?

You create one with nylas calendar virtual create and a single required flag, --email. The value is just a label for the resource; it does not need to resolve or receive mail. The command returns a grant ID you reuse for every booking against that resource, so capture it on first run.

# Mint a bookable calendar for a meeting room
nylas calendar virtual create --email conference-room-a@company.com

# Equipment works the same way — the email is only an identifier
nylas calendar virtual create --email projector-1@company.com --json

Adding --json gives you machine-readable output to pipe into jq when you script the creation of dozens of rooms at once. Naming is the one decision worth making up front: use a stable convention like room-{floor}-{name}@company.com so a 40-room office stays readable in virtual list output instead of becoming 40 opaque identifiers.

How do I list and inspect virtual calendars?

The nylas calendar virtual list command prints every virtual calendar grant in your Nylas application, and virtual show <grant-id> returns the detail for one. Together they answer the two questions you ask most often: which resources exist, and which grant ID maps to a given room.

# Every virtual calendar in the application
nylas calendar virtual list

# Detail for one resource, by grant ID
nylas calendar virtual show vcal-grant-123 --json

For automation, pipe the list through --json and resolve a friendly name to its grant ID instead of hardcoding IDs in scripts. The example below looks up the room created above and stores its grant ID in a shell variable, which keeps a booking script readable when your inventory grows past 10 or 20 resources. Resolving by label also survives a recreate, since a deleted-and-remade room keeps the same --email identifier even though its grant ID changes.

# Resolve "conference-room-a" to its grant ID
GRANT=$(nylas calendar virtual list --json \
  | jq -r '.[] | select(.email == "conference-room-a@company.com") | .id')
echo "$GRANT"

How do I book events against a virtual calendar?

You book a virtual calendar exactly like any other: pass its grant ID as the positional argument to nylas calendar events create, then set a title, start, and end. The event lands on the resource's calendar and marks it busy, so the next availability check sees the room as taken for that window.

# Reserve room A for a 1-hour standup using its grant ID
nylas calendar events create "$GRANT" \
  --title "Sprint standup" \
  --start "2026-06-15 09:00" --end "2026-06-15 09:30" \
  --participant team@company.com

# Confirm the room reads as busy for that window
nylas calendar availability check --emails conference-room-a@company.com \
  --start "2026-06-15 09:00" --duration 8h --json

Events default to --busy, which is what you want for a resource: a booked room must block double-booking. Use nylas calendar events list -c <calendar-id> to read what's on a resource, and events delete to release a slot. Because the calendar has no inbox, no acceptance email is ever sent — the booking is a pure schedule write, which is why a create call typically returns in under 1 second.

Why use a virtual calendar over a shared mailbox?

A virtual calendar avoids the licensing and provisioning cost of a shared mailbox. Google and Microsoft both bill resource calendars against directory objects and tie them to admin-console workflows; a virtual calendar is created in one API-backed CLI call and carries no per-seat cost, which matters when you track 30 rooms or 200 pieces of equipment.

The trade-off is integration scope. A virtual calendar lives inside your Nylas application and is not visible in an end user's native Google or Outlook calendar grid unless you surface it yourself. Microsoft deprecated Basic Auth for Exchange Online in October 2022 and now gates room mailboxes behind Graph application permissions and Azure AD app registration; a virtual calendar sidesteps that registration entirely. Choose virtual calendars when the resource is an internal booking target you control end to end, and choose a provider room mailbox when users must see the resource inside their own first-party calendar app.

Next steps