Use Scheduler with Agent Accounts

Scheduler works with Agent Account grants. Point a Configuration at an Agent Account’s grant_id and the agent becomes the organizer: guests book against the agent’s own calendar, the confirmation email comes from the agent’s own address, and the booking lands on the agent’s primary calendar. No OAuth connection and no human mailbox involved.

That matters when the thing doing the scheduling isn’t a person. A support agent that needs to book a callback, or a recruiting agent that owns its own interview slots, previously had to borrow a human’s connected grant. Now it can hold the Configuration itself.

What works the same as a connected grant

Every Scheduler endpoint takes the same shape for an Agent Account as it does for a Google or Microsoft grant. You call /v3/grants/{grant_id}/scheduling/configurations with the Agent Account’s grant ID, and the Availability, Sessions, and Bookings endpoints behave identically. There’s no separate client, URL prefix, or auth flow.

Configurations. Create, read, update, and delete against the Agent Account grant.
Public and private Configurations. requires_session_auth works either way, and sessions are created the same way.
Nylas-hosted and self-hosted Scheduling Pages. A public Configuration with a slug still gets hosted under book.nylas.com.
Availability rules. Open hours, buffers, and specific-time availability all apply, and available_days_in_future still defaults to 30 days.
Booking flow. Both the booking and organizer-confirmation booking types work, including the confirmation email to the organizer.
Booking webhooks. All five triggers fire: booking.created, booking.pending, booking.rescheduled, booking.cancelled, and booking.reminder.

Because the Agent Account has no OAuth token, you can skip the scopes tables in the Configurations and Bookings references. Those columns cover Google and Microsoft grants; an Agent Account authenticates with your API key alone.

Create a Configuration for an Agent Account

The Create Configuration request below sets up a booking page owned by an Agent Account, with slots 30 minutes long. The participants[].email is the Agent Account’s own address, and both availability.calendar_ids and booking.calendar_id are set to primary because that’s the only calendar Scheduler reads for an Agent Account today.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<AGENT_ACCOUNT_GRANT_ID>/scheduling/configurations" \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Support callback",
    "slug": "support-callback",
    "requires_session_auth": false,
    "participants": [
      {
        "name": "Support Agent",
        "email": "[email protected]",
        "is_organizer": true,
        "availability": {
          "calendar_ids": ["primary"]
        },
        "booking": {
          "calendar_id": "primary"
        }
      }
    ],
    "availability": {
      "duration_minutes": 30
    },
    "event_booking": {
      "title": "Support callback",
      "booking_type": "booking"
    }
  }'

After the Configuration exists, the booking flow is unchanged: a guest picks a slot, POST /v3/scheduling/bookings creates the event on the agent’s primary calendar, and the agent’s mailbox receives the same calendar traffic a human organizer would. See Retrieve booking IDs for reading bookings back.

Only primary calendars are supported

Scheduler reads and writes the Agent Account’s primary calendar only. Set availability.calendar_ids to ["primary"] and booking.calendar_id to "primary" on every Agent Account participant. Agent Accounts can hold additional calendars up to your plan’s cap, but Scheduler reads exactly 1 calendar per Agent Account participant and ignores any others for both availability lookups and event creation.

Two practical consequences:

Everything on the primary calendar counts toward busy time. If the agent also creates events directly through the Events API, those events block booking slots. Keep operational or placeholder events off the primary calendar, or accept that they narrow availability.
You can’t split booking types across calendars. A pattern like “demos on the sales calendar, callbacks on the support calendar” needs one Agent Account per booking type rather than one account with two calendars.

Connected Google and Microsoft grants are unaffected. If a Configuration mixes an Agent Account organizer with connected-grant participants, only the Agent Account participant is restricted to primary.

Round-robin meetings aren’t supported

Agent Accounts can’t participate in round-robin Configurations. Both distribution methods, max-fairness and max-availability, require the availability_method field in availability_rules, and neither works when an Agent Account is in the participants array. Use connected grants for round-robin pools, where Nylas recommends capping the participant list at 10 users for performance.

The other three meeting types work: one-on-one, collective, and group. One-on-one is the natural fit, since an Agent Account represents a single identity rather than a team. Collective meetings work when the agent is one of several required attendees, and group Configurations work for classes or webinars the agent hosts.

If you need round-robin distribution across a pool of agents, do the rotation in your own code: keep one Configuration per Agent Account and pick which booking link to hand out. You lose the key5 fairness bookkeeping that max-fairness does for you, so track the last-booked agent yourself.

Booking notifications

Scheduler emits 5 booking triggers, and all of them fire for Agent Account organizers exactly as they do for connected grants, with the same payload shape. Subscribe with POST /v3/webhooks and read the Scheduler notification schemas for the full field list.

Trigger	What it fires on
`booking.created`	A guest confirms a slot on the agent’s Scheduling Page.
`booking.pending`	A guest books an `organizer-confirmation` slot and the agent hasn’t confirmed yet.
`booking.rescheduled`	A guest moves an existing booking.
`booking.cancelled`	A guest cancels.
`booking.reminder`	The reminder window before the event start time is reached.

Booking webhooks arrive alongside the Agent Account’s own event.created and message.created triggers for the same booking, because the event lands on the agent’s calendar and the confirmation email lands in its mailbox. Pick one trigger to drive your logic. booking.created carries the booking_id and booking_ref you need for reschedule and cancel links, so it’s usually the right one.

Send limits apply to booking email

Booking confirmations, reschedule notices, cancellations, and reminders all send from the Agent Account’s address, so each one counts against the account’s daily send quota. A booking page with reminders turned on generates at least 2 messages per booking: the confirmation, then the reminder, plus anything the guest triggers by rescheduling or cancelling.

If the account is over quota, the event still saves but the email is skipped silently, and the guest sees a confirmed slot with no confirmation in their inbox. Check the quota before you point a high-traffic Scheduling Page at a new Agent Account, and set disable_emails on the Configuration if you’d rather send confirmations from your own system.

What’s next

Meeting types in Nylas Scheduler for the one-on-one, collective, and group Configurations that work with Agent Accounts
Managing availability for open hours, buffers, and specific-time availability rules
How Agent Account calendars work for the Events API surface behind a booking
Supported endpoints for Agent Accounts for the full Agent Account API surface
Scheduling agent with a dedicated identity for an end-to-end tutorial
Configurations API reference for request and response schemas