---
title: "How booking pages work"
description: "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."
url: "https://openemail.uk/docs/api/bookings/overview"
area: "API"
category: "Mailbox"
---

# 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 by `rules`.
- 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`.
- `away` on a page lists those out of office periods. Set `config.busy.outOfOffice` to false to keep a page open through them.
- The time is checked again when a guest books, so one time is never booked twice.
- `problem` says what stops a page from taking bookings: `sender` when `fromEmail` can no longer send, `hours` when nothing is open, `host` when 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 need `calendar:write` and `emails:send`. Deleting a page needs only `calendar: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.