Skip to content
Skip to main content

Use Scheduler with Agent Accounts

Last updated:

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

Section titled “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

Section titled “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. The Agent Account’s email address works in place of primary too.

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.

Add conferencing to Agent Account bookings

Section titled “Add conferencing to Agent Account bookings”

Scheduler adds a Zoom, Google Meet, or Microsoft Teams link to each booking when the Configuration’s event_booking.conferencing object uses autocreate. An Agent Account has no conferencing account of its own, so autocreate.conf_grant_id is required for all 3 providers. Set it to a Zoom, Google, or Microsoft grant in the same application.

"event_booking": {
  "title": "Support callback",
  "conferencing": {
    "provider": "Google Meet",
    "autocreate": {
      "conf_grant_id": "<GOOGLE_GRANT_ID>"
    }
  }
}

The account behind conf_grant_id hosts every meeting booked through the Configuration. If the meeting can’t be created, the slot is still booked without a link. The Agent Account conferencing recipe covers how each provider creates the meeting.

Only primary calendars are supported

Section titled “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. You can use the Agent Account’s email address instead of primary, in any letter case. It resolves to the same primary calendar, and booking responses report that calendar’s real ID. 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

Section titled “Round-robin meetings”

Agent Accounts work as round-robin hosts. Both distribution methods accept an Agent Account grant in the participants array, and a single pool can mix agent and human hosts. Set availability.availability_rules.availability_method to max-fairness or max-availability exactly as you would for a pool of connected grants, and keep the participant list at 10 or fewer for performance.

Max-fairness rotates to whichever host was booked least recently for that meeting type, using the reserved key5 metadata field to tag the events it counts. Max-availability picks the host with the most open time instead. Both read each Agent Account participant’s primary calendar only, so the primary-calendar rule above applies to every agent in the pool.

The other three meeting types work too: 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.

Booking notifications

Section titled “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.

TriggerWhat it fires on
booking.createdA guest confirms a slot on the agent’s Scheduling Page.
booking.pendingA guest books an organizer-confirmation slot and the agent hasn’t confirmed yet.
booking.rescheduledA guest moves an existing booking.
booking.cancelledA guest cancels.
booking.reminderThe 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

Section titled “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

Section titled “What’s next”