How booking pages work
A booking page is a public link where somebody picks a free time and books a meeting on a person’s calendar. The API manages the pages, reads the times they offer, and answers the bookings guests make.
A page, its settings and its bookings
A page has a name, a slug that makes its link /book/<slug>, a status, and a config with everything else. A booking is one meeting a guest booked on a page. It is also a calendar event with the guest invited, named by eventId, so it shows wherever the calendar does.
| Part of `config` | What it holds |
|---|---|
| durations | The meeting lengths a guest can pick, in minutes, up to four |
| location | kind is video, phone, in-person or none, and value is the link or the address |
| availability | The timezone, weekly hours as seven lists with Sunday first, and overrides for single dates. Hours are minutes after midnight, so 540 is 09:00 |
| rules | noticeMinutes, horizonDays, intervalMinutes, bufferBeforeMinutes, bufferAfterMinutes and dailyLimit |
| approval | True holds each booking as a request until it is approved or declined |
| fromEmail | The address the emails are sent from and the calendar events are organised by |
| questions | What the guest is asked besides their name and email |
| guestChanges | Whether a guest may cancel or pick a new time from their emails, and until how long before the meeting |
| busy | Which addresses and subscribed calendars block time, and whether out of office closes the page |
| appearance | The accent colour, the theme, the background and its photo, the fonts, and whether the photo of the person shows |
| seo | The title and the summary for the browser tab and search results, and whether search engines may list the page |
| extraGuests | How many other people a guest may add to a booking, from 0, which is off, to 10 |
What a page offers
- The open hours come from
availability, narrowed byrules. - Taken out are the events the person made, invitations to their addresses they have not declined, calendars they subscribed to, bookings on any of their pages, and the out of office periods of
fromEmail. awayon a page lists those out of office periods. Setconfig.busy.outOfOfficeto false to keep a page open through them.- The time is checked again when a guest books, so one time is never booked twice.
problemsays what stops a page from taking bookings:senderwhenfromEmailcan no longer send,hourswhen nothing is open,hostwhen the person left the workspace.
Whose pages, and which scopes
- A page belongs to one person. An API key acts for the workspace owner and reaches the owner’s pages. A connected app reaches the pages of the person who connected it.
- Reading needs
calendar:read. Creating or changing a page and approving, declining, cancelling, rescheduling or sending again needcalendar:writeandemails:send. Deleting a page needs onlycalendar:write. - A key or app limited to particular addresses is refused with 422
capability_unsupported, because a page reads the whole calendar. - A person holds at most 25 pages: 403
booking_page_limit_reached.
Everything here is also in the SDKs as bookings, in the CLI as nextmail bookings, and in the MCP tools, which the assistant uses too.
Webhook events
Four events tell your systems about booking pages: booking.created when a guest books a time, booking.confirmed when the host accepts a booking that waited for approval, booking.rescheduled when the guest or the host moves it, and booking.cancelled when either of them cancels it or the host declines it. Each carries bookingId, pageId, status, startAt, endAt, guestName, guestEmail, guestTimezone, location, rescheduleCount, endedBy, reason, createdAt and at.
Only the pages of the workspace owner send them, because the calendar behind the page of another member is theirs alone. They are not in the default set, so an endpoint receives them only when it names them in eventTypes, and an endpoint limited to some addresses or domains never does.
Google Workspace
Fastmail