--- title: "Booking pages" description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with." url: "https://openemail.uk/docs/api/reference/booking-pages" area: "API" category: "Reference" --- # Booking pages Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations A booking page is a public link, `/book/`, where somebody picks a free time and books a meeting on a person's calendar. The times it offers are the working hours of the page with everything taken out that makes the person busy: their calendar events, invitations they have not declined, calendars they subscribed to, bookings they already have, the gaps the page keeps around meetings, and the days they are out of office. A booking is a calendar event with the guest invited, so it shows wherever the calendar does. A booking page belongs to one person. An API key acts as the workspace owner and reaches the pages of the owner, and a connected app reaches the pages of the person who connected it. ### `GET /booking-pages` List booking pages Every booking page of the person, oldest first, each with its settings, its public link and how many bookings are upcoming or wait for approval. A booking page belongs to one person. An API key acts as the workspace owner and reaches the pages of the owner, and a connected app reaches the pages of the person who connected it. Requires the `calendar:read` scope. - Scopes: `calendar:read`. **Returns** - `200` `BookingPageList`: The booking pages. **Errors** - `422`: `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `400`, `401`, `403`, `404`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.listPages()`](https://openemail.uk/docs/sdk/reference/bookings#listPages); Python [`bookings.list_pages()`](https://openemail.uk/docs/python/reference/bookings#listPages); Ruby [`bookings.list_pages`](https://openemail.uk/docs/ruby/reference/bookings#listPages); PHP [`bookings->listPages`](https://openemail.uk/docs/php/reference/bookings#listPages); Go [`Bookings.ListPages`](https://openemail.uk/docs/go/reference/bookings#listPages); Java [`bookings().listPages`](https://openemail.uk/docs/java/reference/bookings#listPages); C# [`Bookings.ListPagesAsync`](https://openemail.uk/docs/csharp/reference/bookings#listPages); CLI [`openemail bookings list-pages`](https://openemail.uk/docs/cli/reference/bookings#bookings-list-pages); MCP [`listBookingPages`](https://openemail.uk/docs/mcp/tools/bookings#listBookingPages). ### `POST /booking-pages` Create a booking page Creates a booking page that takes bookings at once. Only `name` is required: the page starts with weekdays from 09:00 to 17:00, 30 minute meetings, four hours of notice and the first address the person may send from. Anything in `config` replaces that default. A person holds at most 25 pages. Requires the `calendar:write` and `emails:send` scopes. - Scopes: `calendar:write`, `emails:send`. **Request body** - `name` (`string`, required, 1 to 80 characters): What the page is called, shown to guests as its heading, such as `Intro call`. - `slug` (`string`, 1 to 60 characters): The last part of the public link, `/book/`: lowercase letters, digits and hyphens. Left out, it is made from the name. It is unique across OpenEmail. - `timezone` (`string`, 1 to 64 characters): The IANA time zone the working hours are read in, such as `Europe/Berlin`, for a new page whose `config.availability.timezone` is not sent. Defaults to `UTC`. - `config` (`object`): The settings of the page. Send only the parts that change: a top-level value replaces the stored one, and inside `location`, `availability`, `rules`, `appearance`, `guestChanges`, `busy` and `seo` each field is merged on its own. A list (`durations`, `questions`, `availability.weekly`, `availability.overrides`) is replaced whole. - `description` (`string`, up to 2000 characters): Text shown under the name of the page. Basic Markdown works: bold, italic, links and lists. - `hostName` (`string`, up to 80 characters): The name guests see as the person they meet. Defaults to the name of the account. - `durations` (`integer[]`, 1 to 4 items): The meeting lengths a guest can pick, in minutes, each a multiple of 5 between 5 and 720. - `approval` (`boolean`): True holds each new booking as a request until it is approved or declined. False confirms it at once. - `fromEmail` (`string`, up to 320 characters): The address the booking emails are sent from and the calendar events are organised by. It has to be one the owner of the page may send from. - `notifyHost` (`boolean`): Whether that address gets an email about each new, moved or cancelled booking. - `questions` (`object[]`, up to 10 items): What the guest is asked besides their name and email, at most 10. - `id` (`string`, required, pattern `^[a-z0-9]{4,16}$`): A stable key for the answers: 4 to 16 lowercase letters and digits, unique on the page. `name`, `email`, `phone`, `timezone` and `start` are taken. - `kind` (`string`, required, one of `"text"`, `"long-text"`, `"phone"`, `"choice"`, `"checkbox"`): `text`, `long-text`, `phone`, `choice` (one of `options`) or `checkbox`. - `label` (`string`, required, 1 to 120 characters) - `required` (`boolean`, required) - `options` (`string[]`, required, up to 12 items): The answers of a `choice` question, at least two. Empty for the other kinds. - `confirmation` (`string`, up to 1000 characters): Text shown to the guest after booking, and added to the confirmation email. - `redirectUrl` (`string`, up to 2000 characters): An `https://` page to send the guest to after booking, or empty. - `extraGuests` (`integer`, at least 0, at most 10): How many other people a guest may add to a booking, 0 to 10. Each one gets the invitation and every later change. Defaults to 0, which hides the field. - `location` (`object`): Where the meeting happens. - `kind` (`string`, one of `"video"`, `"phone"`, `"in-person"`, `"none"`): `video` with a fixed link in `value`, `phone` (the guest is asked for a number), `in-person` with the address in `value`, or `none`. - `value` (`string`, up to 500 characters): The `https://` link of a `video` meeting or the address of an `in-person` one. - `availability` (`object`): When the page offers times, before the calendar is taken out. - `timezone` (`string`, 1 to 64 characters): The IANA time zone the hours below are read in. - `weekly` (`object[][]`, 7 to 7 items): Seven lists, Sunday first, of the hours open on that weekday. An empty list closes the day. - `start` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range opens, so `540` is 09:00. - `end` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range closes, later than `start`. - `overrides` (`object[]`, up to 180 items): Dates with their own hours, at most 180. `date` is `YYYY-MM-DD` in the time zone of the page, and an empty `ranges` closes that date. - `date` (`string`, required) - `ranges` (`object[]`, required, up to 6 items) - `start` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range opens, so `540` is 09:00. - `end` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range closes, later than `start`. - `rules` (`object`): The limits on which of the open hours are offered. - `noticeMinutes` (`integer`, at least 0, at most 43200): How many minutes ahead a booking has to be made. - `horizonDays` (`integer`, at least 1, at most 365): How many days ahead the page offers times, up to 365. - `intervalMinutes` (`integer`, nullable): Minutes between two start times, one of 5, 10, 15, 20, 30, 45, 60, 90, 120. Null steps by the length of the meeting. - `bufferBeforeMinutes` (`integer`, at least 0, at most 240): Minutes kept free before every meeting, up to 240. - `bufferAfterMinutes` (`integer`, at least 0, at most 240): Minutes kept free after every meeting, up to 240. - `dailyLimit` (`integer`, nullable, at least 1, at most 50): The most bookings this page takes on one day, up to 50. Null for no limit. - `appearance` (`object`): How the public page looks. - `accent` (`string`, pattern `^#[0-9a-f]{6}$`): The colour of buttons and the picked day, as `#rrggbb`. - `theme` (`string`, one of `"auto"`, `"light"`, `"dark"`): `auto` follows the device of the guest, or force `light` or `dark`. - `showAvatar` (`boolean`) - `guestChanges` (`object`): What a guest may do from the link in their emails. - `cancel` (`boolean`) - `reschedule` (`boolean`) - `cutoffMinutes` (`integer`, at least 0, at most 20160): How many minutes before the meeting those changes close. - `busy` (`object`): What counts as busy besides the events the person made and the bookings they already have. - `addresses` (`string[]`, nullable, up to 50 items): The addresses whose invitations block time unless declined. Null checks every address the person holds. - `subscriptions` (`boolean`): Whether events from calendars the person subscribed to block time. - `outOfOffice` (`boolean`, default `true`): Whether the page offers no times while `fromEmail` is out of office. Defaults to true. - `seo` (`object`): How the public page presents itself to browsers and search engines. - `title` (`string`, up to 120 characters, default `""`): The title of the browser tab and of a search result. Empty uses the name of the page and the host. - `description` (`string`, up to 300 characters, default `""`): The summary under the title in a search result. Empty uses the start of the description. - `indexable` (`boolean`, default `false`): Whether search engines may list the page. False, the default, asks them not to. **Returns** - `201` `BookingPage`: The page as it is stored. **Errors** - `403`: The key lacks a scope. `booking_page_limit_reached`: the person holds as many pages as they may. - `409`: `booking_link_taken`: another page already uses that `slug`. - `422`: `invalid_parameter`: a field is missing or malformed. `invalid_booking_page`: the link, the sender or a setting is not valid, as the message says. `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `400`, `401`, `404`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.createPage()`](https://openemail.uk/docs/sdk/reference/bookings#createPage); Python [`bookings.create_page()`](https://openemail.uk/docs/python/reference/bookings#createPage); Ruby [`bookings.create_page`](https://openemail.uk/docs/ruby/reference/bookings#createPage); PHP [`bookings->createPage`](https://openemail.uk/docs/php/reference/bookings#createPage); Go [`Bookings.CreatePage`](https://openemail.uk/docs/go/reference/bookings#createPage); Java [`bookings().createPage`](https://openemail.uk/docs/java/reference/bookings#createPage); C# [`Bookings.CreatePageAsync`](https://openemail.uk/docs/csharp/reference/bookings#createPage); CLI [`openemail bookings create-page`](https://openemail.uk/docs/cli/reference/bookings#bookings-create-page); MCP [`createBookingPage`](https://openemail.uk/docs/mcp/tools/bookings#createBookingPage). ### `GET /booking-pages/{id}` Read a booking page One booking page with every setting, what stops it from taking bookings if anything does, and the out of office periods that close it. Requires the `calendar:read` scope. - Scopes: `calendar:read`. **Path parameters** - `id` (`string`, required): The booking page, such as `bkp_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /booking-pages` lists it. **Returns** - `200` `BookingPage`: The page. **Errors** - `404`: `booking_page_not_found`: the person has no booking page with that id. - `422`: `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `400`, `401`, `403`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.getPage()`](https://openemail.uk/docs/sdk/reference/bookings#getPage); Python [`bookings.get_page()`](https://openemail.uk/docs/python/reference/bookings#getPage); Ruby [`bookings.get_page`](https://openemail.uk/docs/ruby/reference/bookings#getPage); PHP [`bookings->getPage`](https://openemail.uk/docs/php/reference/bookings#getPage); Go [`Bookings.GetPage`](https://openemail.uk/docs/go/reference/bookings#getPage); Java [`bookings().getPage`](https://openemail.uk/docs/java/reference/bookings#getPage); C# [`Bookings.GetPageAsync`](https://openemail.uk/docs/csharp/reference/bookings#getPage); CLI [`openemail bookings get-page`](https://openemail.uk/docs/cli/reference/bookings#bookings-get-page); MCP [`getBookingPage`](https://openemail.uk/docs/mcp/tools/bookings#getBookingPage). ### `PATCH /booking-pages/{id}` Update a booking page Changes the name, the link, the status or any setting of a page. Send only what changes. Set `status` to `paused` to stop offering times without losing the link. Bookings already made keep their time, and a new `slug` stops the old link from working. Requires the `calendar:write` and `emails:send` scopes. - Scopes: `calendar:write`, `emails:send`. **Path parameters** - `id` (`string`, required): The booking page, such as `bkp_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /booking-pages` lists it. **Request body** - `name` (`string`, 1 to 80 characters): What the page is called, shown to guests as its heading, such as `Intro call`. - `slug` (`string`, 1 to 60 characters): The last part of the public link, `/book/`: lowercase letters, digits and hyphens. Left out, it is made from the name. It is unique across OpenEmail. - `status` (`string`, one of `"active"`, `"paused"`): `active` takes bookings. `paused` keeps the link working but offers no times. - `config` (`object`): The settings of the page. Send only the parts that change: a top-level value replaces the stored one, and inside `location`, `availability`, `rules`, `appearance`, `guestChanges`, `busy` and `seo` each field is merged on its own. A list (`durations`, `questions`, `availability.weekly`, `availability.overrides`) is replaced whole. - `description` (`string`, up to 2000 characters): Text shown under the name of the page. Basic Markdown works: bold, italic, links and lists. - `hostName` (`string`, up to 80 characters): The name guests see as the person they meet. Defaults to the name of the account. - `durations` (`integer[]`, 1 to 4 items): The meeting lengths a guest can pick, in minutes, each a multiple of 5 between 5 and 720. - `approval` (`boolean`): True holds each new booking as a request until it is approved or declined. False confirms it at once. - `fromEmail` (`string`, up to 320 characters): The address the booking emails are sent from and the calendar events are organised by. It has to be one the owner of the page may send from. - `notifyHost` (`boolean`): Whether that address gets an email about each new, moved or cancelled booking. - `questions` (`object[]`, up to 10 items): What the guest is asked besides their name and email, at most 10. - `id` (`string`, required, pattern `^[a-z0-9]{4,16}$`): A stable key for the answers: 4 to 16 lowercase letters and digits, unique on the page. `name`, `email`, `phone`, `timezone` and `start` are taken. - `kind` (`string`, required, one of `"text"`, `"long-text"`, `"phone"`, `"choice"`, `"checkbox"`): `text`, `long-text`, `phone`, `choice` (one of `options`) or `checkbox`. - `label` (`string`, required, 1 to 120 characters) - `required` (`boolean`, required) - `options` (`string[]`, required, up to 12 items): The answers of a `choice` question, at least two. Empty for the other kinds. - `confirmation` (`string`, up to 1000 characters): Text shown to the guest after booking, and added to the confirmation email. - `redirectUrl` (`string`, up to 2000 characters): An `https://` page to send the guest to after booking, or empty. - `extraGuests` (`integer`, at least 0, at most 10): How many other people a guest may add to a booking, 0 to 10. Each one gets the invitation and every later change. Defaults to 0, which hides the field. - `location` (`object`): Where the meeting happens. - `kind` (`string`, one of `"video"`, `"phone"`, `"in-person"`, `"none"`): `video` with a fixed link in `value`, `phone` (the guest is asked for a number), `in-person` with the address in `value`, or `none`. - `value` (`string`, up to 500 characters): The `https://` link of a `video` meeting or the address of an `in-person` one. - `availability` (`object`): When the page offers times, before the calendar is taken out. - `timezone` (`string`, 1 to 64 characters): The IANA time zone the hours below are read in. - `weekly` (`object[][]`, 7 to 7 items): Seven lists, Sunday first, of the hours open on that weekday. An empty list closes the day. - `start` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range opens, so `540` is 09:00. - `end` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range closes, later than `start`. - `overrides` (`object[]`, up to 180 items): Dates with their own hours, at most 180. `date` is `YYYY-MM-DD` in the time zone of the page, and an empty `ranges` closes that date. - `date` (`string`, required) - `ranges` (`object[]`, required, up to 6 items) - `start` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range opens, so `540` is 09:00. - `end` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range closes, later than `start`. - `rules` (`object`): The limits on which of the open hours are offered. - `noticeMinutes` (`integer`, at least 0, at most 43200): How many minutes ahead a booking has to be made. - `horizonDays` (`integer`, at least 1, at most 365): How many days ahead the page offers times, up to 365. - `intervalMinutes` (`integer`, nullable): Minutes between two start times, one of 5, 10, 15, 20, 30, 45, 60, 90, 120. Null steps by the length of the meeting. - `bufferBeforeMinutes` (`integer`, at least 0, at most 240): Minutes kept free before every meeting, up to 240. - `bufferAfterMinutes` (`integer`, at least 0, at most 240): Minutes kept free after every meeting, up to 240. - `dailyLimit` (`integer`, nullable, at least 1, at most 50): The most bookings this page takes on one day, up to 50. Null for no limit. - `appearance` (`object`): How the public page looks. - `accent` (`string`, pattern `^#[0-9a-f]{6}$`): The colour of buttons and the picked day, as `#rrggbb`. - `theme` (`string`, one of `"auto"`, `"light"`, `"dark"`): `auto` follows the device of the guest, or force `light` or `dark`. - `showAvatar` (`boolean`) - `guestChanges` (`object`): What a guest may do from the link in their emails. - `cancel` (`boolean`) - `reschedule` (`boolean`) - `cutoffMinutes` (`integer`, at least 0, at most 20160): How many minutes before the meeting those changes close. - `busy` (`object`): What counts as busy besides the events the person made and the bookings they already have. - `addresses` (`string[]`, nullable, up to 50 items): The addresses whose invitations block time unless declined. Null checks every address the person holds. - `subscriptions` (`boolean`): Whether events from calendars the person subscribed to block time. - `outOfOffice` (`boolean`, default `true`): Whether the page offers no times while `fromEmail` is out of office. Defaults to true. - `seo` (`object`): How the public page presents itself to browsers and search engines. - `title` (`string`, up to 120 characters, default `""`): The title of the browser tab and of a search result. Empty uses the name of the page and the host. - `description` (`string`, up to 300 characters, default `""`): The summary under the title in a search result. Empty uses the start of the description. - `indexable` (`boolean`, default `false`): Whether search engines may list the page. False, the default, asks them not to. **Returns** - `200` `BookingPage`: The page after the change. **Errors** - `404`: `booking_page_not_found`: the person has no booking page with that id. - `409`: `booking_link_taken`: another page already uses that `slug`. - `422`: `invalid_parameter`: nothing to change was sent or a field is malformed. `invalid_booking_page`: the link, the sender or a setting is not valid, as the message says. `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `400`, `401`, `403`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.updatePage()`](https://openemail.uk/docs/sdk/reference/bookings#updatePage); Python [`bookings.update_page()`](https://openemail.uk/docs/python/reference/bookings#updatePage); Ruby [`bookings.update_page`](https://openemail.uk/docs/ruby/reference/bookings#updatePage); PHP [`bookings->updatePage`](https://openemail.uk/docs/php/reference/bookings#updatePage); Go [`Bookings.UpdatePage`](https://openemail.uk/docs/go/reference/bookings#updatePage); Java [`bookings().updatePage`](https://openemail.uk/docs/java/reference/bookings#updatePage); C# [`Bookings.UpdatePageAsync`](https://openemail.uk/docs/csharp/reference/bookings#updatePage); CLI [`openemail bookings update-page`](https://openemail.uk/docs/cli/reference/bookings#bookings-update-page); MCP [`updateBookingPage`](https://openemail.uk/docs/mcp/tools/bookings#updateBookingPage). ### `DELETE /booking-pages/{id}` Delete a booking page Deletes a booking page for good. Its link stops working and the list of its bookings goes with it, so guests can no longer move or cancel through their links. The meetings already booked stay on the calendar. Requires the `calendar:write` scope. - Scopes: `calendar:write`. **Path parameters** - `id` (`string`, required): The booking page, such as `bkp_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /booking-pages` lists it. **Returns** - `200` `DeletedBookingPage`: Deleted. **Errors** - `404`: `booking_page_not_found`: the person has no booking page with that id. - `422`: `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `400`, `401`, `403`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.deletePage()`](https://openemail.uk/docs/sdk/reference/bookings#deletePage); Python [`bookings.delete_page()`](https://openemail.uk/docs/python/reference/bookings#deletePage); Ruby [`bookings.delete_page`](https://openemail.uk/docs/ruby/reference/bookings#deletePage); PHP [`bookings->deletePage`](https://openemail.uk/docs/php/reference/bookings#deletePage); Go [`Bookings.DeletePage`](https://openemail.uk/docs/go/reference/bookings#deletePage); Java [`bookings().deletePage`](https://openemail.uk/docs/java/reference/bookings#deletePage); C# [`Bookings.DeletePageAsync`](https://openemail.uk/docs/csharp/reference/bookings#deletePage); CLI [`openemail bookings delete-page`](https://openemail.uk/docs/cli/reference/bookings#bookings-delete-page); MCP [`deleteBookingPage`](https://openemail.uk/docs/mcp/tools/bookings#deleteBookingPage). ### `GET /booking-pages/{id}/times` List the open times of a booking page The start times a guest could book in a window, in order: the hours of the page with the calendar, other bookings, the gaps around meetings, the daily limit, the notice and the out of office periods taken out. A paused page still answers, and a page with a `problem` offers nothing. Requires the `calendar:read` scope. - Scopes: `calendar:read`. **Path parameters** - `id` (`string`, required): The booking page, such as `bkp_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /booking-pages` lists it. **Query parameters** - `from` (`string`, format `date-time`): The start of the window. Defaults to now. - `to` (`string`, format `date-time`): The end of the window, later than `from`. Defaults to 14 days after `from`, and counts for at most 62 days after it. - `durationMinutes` (`integer`, at least 1): The meeting length in minutes, one of the `durations` of the page. Defaults to the shortest. **Returns** - `200` `BookingTimes`: The open times. **Errors** - `404`: `booking_page_not_found`: the person has no booking page with that id. - `422`: `invalid_parameter`: `to` is not later than `from`, or `durationMinutes` is not a length the page offers. `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `400`, `401`, `403`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.listTimes()`](https://openemail.uk/docs/sdk/reference/bookings#listTimes); Python [`bookings.list_times()`](https://openemail.uk/docs/python/reference/bookings#listTimes); Ruby [`bookings.list_times`](https://openemail.uk/docs/ruby/reference/bookings#listTimes); PHP [`bookings->listTimes`](https://openemail.uk/docs/php/reference/bookings#listTimes); Go [`Bookings.ListTimes`](https://openemail.uk/docs/go/reference/bookings#listTimes); Java [`bookings().listTimes`](https://openemail.uk/docs/java/reference/bookings#listTimes); C# [`Bookings.ListTimesAsync`](https://openemail.uk/docs/csharp/reference/bookings#listTimes); CLI [`openemail bookings list-times`](https://openemail.uk/docs/cli/reference/bookings#bookings-list-times). ### `GET /bookings` List bookings The meetings guests booked on the pages of the person, or on one page with `pageId`. `upcoming` and `pending` come soonest first, `past` and `ended` latest first. One guest address holds at most 3 upcoming bookings on a page. Requires the `calendar:read` scope. - Scopes: `calendar:read`. **Query parameters** - `view` (`string`, one of `"upcoming"`, `"pending"`, `"past"`, `"ended"`): Which bookings to list: `upcoming`, `pending`, `past` or `ended`. Defaults to `upcoming`. - `pageId` (`string`, 1 to 64 characters): Only the bookings of this booking page, by its id. Left out, the bookings of every page of the person are listed. - `limit` (`integer`, at least 1, at most 100): Page size, from 1 to 100. The server defaults to 30. - `cursor` (`string`, 1 to 256 characters): The `nextCursor` of the previous page, passed back as it came. Leave it out for the first page. **Returns** - `200` `BookingList`: A page of bookings. **Errors** - `400`: `invalid_cursor`. - `404`: `booking_page_not_found`: the person has no booking page with that id. - `422`: `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `401`, `403`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.list()`](https://openemail.uk/docs/sdk/reference/bookings#list), [`bookings.listAll()`](https://openemail.uk/docs/sdk/reference/bookings#listAll), [`bookings.iterate()`](https://openemail.uk/docs/sdk/reference/bookings#iterate); Python [`bookings.list()`](https://openemail.uk/docs/python/reference/bookings#list), [`bookings.list_all()`](https://openemail.uk/docs/python/reference/bookings#listAll), [`bookings.iterate()`](https://openemail.uk/docs/python/reference/bookings#iterate); Ruby [`bookings.list`](https://openemail.uk/docs/ruby/reference/bookings#list), [`bookings.list_all`](https://openemail.uk/docs/ruby/reference/bookings#listAll), [`bookings.iterate`](https://openemail.uk/docs/ruby/reference/bookings#iterate); PHP [`bookings->list`](https://openemail.uk/docs/php/reference/bookings#list), [`bookings->listAll`](https://openemail.uk/docs/php/reference/bookings#listAll), [`bookings->iterate`](https://openemail.uk/docs/php/reference/bookings#iterate); Go [`Bookings.List`](https://openemail.uk/docs/go/reference/bookings#list), [`Bookings.ListAll`](https://openemail.uk/docs/go/reference/bookings#listAll), [`Bookings.Iterate`](https://openemail.uk/docs/go/reference/bookings#iterate); Java [`bookings().list`](https://openemail.uk/docs/java/reference/bookings#list), [`bookings().listAll`](https://openemail.uk/docs/java/reference/bookings#listAll), [`bookings().iterate`](https://openemail.uk/docs/java/reference/bookings#iterate); C# [`Bookings.ListAsync`](https://openemail.uk/docs/csharp/reference/bookings#list), [`Bookings.ListAllAsync`](https://openemail.uk/docs/csharp/reference/bookings#listAll), [`Bookings.IterateAsync`](https://openemail.uk/docs/csharp/reference/bookings#iterate); CLI [`openemail bookings list`](https://openemail.uk/docs/cli/reference/bookings#bookings-list); MCP [`listBookings`](https://openemail.uk/docs/mcp/tools/bookings#listBookings). ### `GET /bookings/{id}` Read a booking One booking with the guest, their answers, the calendar event it is and how it ended if it did. A booking follows its calendar event, so a meeting moved or cancelled in the calendar reads as moved or cancelled here. Requires the `calendar:read` scope. - Scopes: `calendar:read`. **Path parameters** - `id` (`string`, required): The booking, such as `bkg_2b8d4f6a1c3e5079b6d8f0a2`, as `GET /bookings` lists it. **Returns** - `200` `Booking`: The booking. **Errors** - `404`: `booking_not_found`: the person has no booking with that id. - `422`: `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `400`, `401`, `403`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.get()`](https://openemail.uk/docs/sdk/reference/bookings#get); Python [`bookings.get()`](https://openemail.uk/docs/python/reference/bookings#get); Ruby [`bookings.get`](https://openemail.uk/docs/ruby/reference/bookings#get); PHP [`bookings->get`](https://openemail.uk/docs/php/reference/bookings#get); Go [`Bookings.Get`](https://openemail.uk/docs/go/reference/bookings#get); Java [`bookings().get`](https://openemail.uk/docs/java/reference/bookings#get); C# [`Bookings.GetAsync`](https://openemail.uk/docs/csharp/reference/bookings#get); CLI [`openemail bookings get`](https://openemail.uk/docs/cli/reference/bookings#bookings-get); MCP [`getBooking`](https://openemail.uk/docs/mcp/tools/bookings#getBooking). ### `POST /bookings/{id}/approve` Approve a booking Confirms a booking that waits for approval, on a page whose `config.approval` is true. The hold on the calendar becomes a confirmed meeting. The guest is told by email, sent from the address of the page with the calendar invitation or its cancellation attached. Requires the `calendar:write` and `emails:send` scopes. - Scopes: `calendar:write`, `emails:send`. **Path parameters** - `id` (`string`, required): The booking, such as `bkg_2b8d4f6a1c3e5079b6d8f0a2`, as `GET /bookings` lists it. **Returns** - `200` `Booking`: The booking, confirmed. **Errors** - `404`: `booking_not_found`: the person has no booking with that id. - `409`: `booking_not_pending`: the booking is not waiting for approval. `booking_ended`: its time has passed. - `422`: `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `400`, `401`, `403`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.approve()`](https://openemail.uk/docs/sdk/reference/bookings#approve); Python [`bookings.approve()`](https://openemail.uk/docs/python/reference/bookings#approve); Ruby [`bookings.approve`](https://openemail.uk/docs/ruby/reference/bookings#approve); PHP [`bookings->approve`](https://openemail.uk/docs/php/reference/bookings#approve); Go [`Bookings.Approve`](https://openemail.uk/docs/go/reference/bookings#approve); Java [`bookings().approve`](https://openemail.uk/docs/java/reference/bookings#approve); C# [`Bookings.ApproveAsync`](https://openemail.uk/docs/csharp/reference/bookings#approve); CLI [`openemail bookings approve`](https://openemail.uk/docs/cli/reference/bookings#bookings-approve); MCP [`approveBooking`](https://openemail.uk/docs/mcp/tools/bookings#approveBooking). ### `POST /bookings/{id}/decline` Decline a booking Turns down a booking that waits for approval and frees its time. The guest is told by email, sent from the address of the page with the calendar invitation or its cancellation attached. Requires the `calendar:write` and `emails:send` scopes. - Scopes: `calendar:write`, `emails:send`. **Path parameters** - `id` (`string`, required): The booking, such as `bkg_2b8d4f6a1c3e5079b6d8f0a2`, as `GET /bookings` lists it. **Request body** - `reason` (`string`, nullable, up to 500 characters): A sentence for the guest, at most 500 characters, included in the email they get. **Returns** - `200` `Booking`: The booking, declined. **Errors** - `404`: `booking_not_found`: the person has no booking with that id. - `409`: `booking_not_pending`: the booking is not waiting for approval. - `422`: `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `400`, `401`, `403`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.decline()`](https://openemail.uk/docs/sdk/reference/bookings#decline); Python [`bookings.decline()`](https://openemail.uk/docs/python/reference/bookings#decline); Ruby [`bookings.decline`](https://openemail.uk/docs/ruby/reference/bookings#decline); PHP [`bookings->decline`](https://openemail.uk/docs/php/reference/bookings#decline); Go [`Bookings.Decline`](https://openemail.uk/docs/go/reference/bookings#decline); Java [`bookings().decline`](https://openemail.uk/docs/java/reference/bookings#decline); C# [`Bookings.DeclineAsync`](https://openemail.uk/docs/csharp/reference/bookings#decline); CLI [`openemail bookings decline`](https://openemail.uk/docs/cli/reference/bookings#bookings-decline); MCP [`declineBooking`](https://openemail.uk/docs/mcp/tools/bookings#declineBooking). ### `POST /bookings/{id}/cancel` Cancel a booking Cancels a meeting that has not ended yet and cancels its calendar event. A booking that still waits for approval is declined instead. The guest is told by email, sent from the address of the page with the calendar invitation or its cancellation attached. Requires the `calendar:write` and `emails:send` scopes. - Scopes: `calendar:write`, `emails:send`. **Path parameters** - `id` (`string`, required): The booking, such as `bkg_2b8d4f6a1c3e5079b6d8f0a2`, as `GET /bookings` lists it. **Request body** - `reason` (`string`, nullable, up to 500 characters): A sentence for the guest, at most 500 characters, included in the email they get. **Returns** - `200` `Booking`: The booking, cancelled. **Errors** - `404`: `booking_not_found`: the person has no booking with that id. - `409`: `booking_ended`: the booking was already declined or cancelled, or the meeting is over. - `422`: `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `400`, `401`, `403`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.cancel()`](https://openemail.uk/docs/sdk/reference/bookings#cancel); Python [`bookings.cancel()`](https://openemail.uk/docs/python/reference/bookings#cancel); Ruby [`bookings.cancel`](https://openemail.uk/docs/ruby/reference/bookings#cancel); PHP [`bookings->cancel`](https://openemail.uk/docs/php/reference/bookings#cancel); Go [`Bookings.Cancel`](https://openemail.uk/docs/go/reference/bookings#cancel); Java [`bookings().cancel`](https://openemail.uk/docs/java/reference/bookings#cancel); C# [`Bookings.CancelAsync`](https://openemail.uk/docs/csharp/reference/bookings#cancel); CLI [`openemail bookings cancel`](https://openemail.uk/docs/cli/reference/bookings#bookings-cancel); MCP [`cancelBooking`](https://openemail.uk/docs/mcp/tools/bookings#cancelBooking). ### `POST /bookings/{id}/resend` Send the booking email again Sends the guest the email that matches where the booking stands now: the request, the confirmation with its invitation, or the notice that it was declined or cancelled. Use it when `guestMailFailed` is true. Requires the `calendar:write` and `emails:send` scopes. - Scopes: `calendar:write`, `emails:send`. **Path parameters** - `id` (`string`, required): The booking, such as `bkg_2b8d4f6a1c3e5079b6d8f0a2`, as `GET /bookings` lists it. **Returns** - `200` `Booking`: The booking, with `guestMailFailed` as it is after the send. **Errors** - `404`: `booking_not_found`: the person has no booking with that id. - `422`: `capability_unsupported`: the key or app is limited to particular addresses. - The errors every operation can return: `400`, `401`, `403`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`bookings.resendEmail()`](https://openemail.uk/docs/sdk/reference/bookings#resendEmail); Python [`bookings.resend_email()`](https://openemail.uk/docs/python/reference/bookings#resendEmail); Ruby [`bookings.resend_email`](https://openemail.uk/docs/ruby/reference/bookings#resendEmail); PHP [`bookings->resendEmail`](https://openemail.uk/docs/php/reference/bookings#resendEmail); Go [`Bookings.ResendEmail`](https://openemail.uk/docs/go/reference/bookings#resendEmail); Java [`bookings().resendEmail`](https://openemail.uk/docs/java/reference/bookings#resendEmail); C# [`Bookings.ResendEmailAsync`](https://openemail.uk/docs/csharp/reference/bookings#resendEmail); CLI [`openemail bookings resend-email`](https://openemail.uk/docs/cli/reference/bookings#bookings-resend-email); MCP [`resendBookingEmail`](https://openemail.uk/docs/mcp/tools/bookings#resendBookingEmail). ### Objects #### `Booking` `object` - `object` (`string`, required, one of `"booking"`) - `id` (`string`, required): The id, which starts with `bkg_`. - `pageId` (`string`, required): The booking page it was made on. - `pageName` (`string`, required) - `status` (`string`, required, one of `"pending"`, `"confirmed"`, `"declined"`, `"cancelled"`): `pending` while it waits for approval, `confirmed` once the meeting stands, `declined` when a request was turned down, and `cancelled` when a confirmed meeting was called off. - `expired` (`boolean`, required): True for a request nobody answered before its time came. - `past` (`boolean`, required): True once the meeting is over. - `start` (`string`, required, format `date-time`): When the meeting starts. - `end` (`string`, required, format `date-time`): When it ends. - `durationMinutes` (`integer`, required) - `guest` (`object`, required) - `name` (`string`, required) - `email` (`string`, required, format `email`) - `timezone` (`string`, required): The time zone the guest booked in, which their emails use. - `guests` (`string[]`, required): The other people invited to the meeting: the ones the guest added when booking, and anyone added to the calendar event since. Empty when there are none. - `answers` (`object[]`, required): What the guest answered to the questions of the page. - `id` (`string`, required): The `id` of the question. - `label` (`string`, required): The question as it was asked. - `kind` (`string`, required, one of `"text"`, `"long-text"`, `"phone"`, `"choice"`, `"checkbox"`) - `value` (`string`, required): The answer. A `checkbox` answers `yes` or `no`. - `location` (`string`, required): Where the meeting happens, as the guest was told: the link, the phone number or the address. - `eventId` (`string`, required, nullable): The calendar event of the booking, as `GET /calendar/events/{id}` reads it. Null once the booking ended and its event was removed. - `endedBy` (`string`, required, nullable, one of `"host"`, `"guest"`): Who declined or cancelled it. - `endReason` (`string`, required, nullable): The reason they gave. - `rescheduleCount` (`integer`, required, at least 0): How often the meeting was moved. - `guestMailFailed` (`boolean`, required): True when the last email to the guest could not be sent. `POST /bookings/{id}/resend` tries again. - `createdAt` (`string`, required, format `date-time`): When the guest booked. #### `BookingList` `object` - `object` (`string`, one of `"list"`) - `data` (`Booking[]`) - `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it. - `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged. #### `BookingPage` `object` - `object` (`string`, required, one of `"booking_page"`) - `id` (`string`, required): The id, which starts with `bkp_`. - `slug` (`string`, required): The last part of the public link, `/book/`: lowercase letters, digits and hyphens. Left out, it is made from the name. It is unique across OpenEmail. - `name` (`string`, required): What the page is called, shown to guests as its heading, such as `Intro call`. - `status` (`string`, required, one of `"active"`, `"paused"`): `active` takes bookings. `paused` keeps the link working but offers no times. - `url` (`string`, required): The public link to hand to guests. - `problem` (`string`, required, nullable, one of `"sender"`, `"host"`, `"hours"`): What stops the page from taking bookings, or null: `sender` when `config.fromEmail` can no longer send, `hours` when no hours are open at all, and `host` when the person left the workspace. - `config` (`BookingPageConfig`, required) - `counts` (`object`, required) - `upcoming` (`integer`, required, at least 0): Confirmed bookings that have not started. - `pending` (`integer`, required, at least 0): Bookings that wait for approval. - `away` (`object[]`, required): The out of office periods of `config.fromEmail` that are running or still to come. While `config.busy.outOfOffice` is true the page offers no times inside them. - `address` (`string`, required): The address, or the catch-all such as `*@example.com`, that is out of office. - `startsAt` (`string`, required, format `date-time`): When the period starts. - `endsAt` (`string`, required, nullable, format `date-time`): When it ends, or null while it has no end date. - `createdAt` (`string`, required, format `date-time`): When the page was created. - `updatedAt` (`string`, required, format `date-time`): When the page last changed. #### `BookingPageConfig` `object` - `description` (`string`, required, up to 2000 characters): Text shown under the name of the page. Basic Markdown works: bold, italic, links and lists. - `hostName` (`string`, required, up to 80 characters): The name guests see as the person they meet. Defaults to the name of the account. - `durations` (`integer[]`, required, 1 to 4 items): The meeting lengths a guest can pick, in minutes, each a multiple of 5 between 5 and 720. - `approval` (`boolean`, required): True holds each new booking as a request until it is approved or declined. False confirms it at once. - `fromEmail` (`string`, required, up to 320 characters): The address the booking emails are sent from and the calendar events are organised by. It has to be one the owner of the page may send from. - `notifyHost` (`boolean`, required): Whether that address gets an email about each new, moved or cancelled booking. - `questions` (`object[]`, required, up to 10 items): What the guest is asked besides their name and email, at most 10. - `id` (`string`, required, pattern `^[a-z0-9]{4,16}$`): A stable key for the answers: 4 to 16 lowercase letters and digits, unique on the page. `name`, `email`, `phone`, `timezone` and `start` are taken. - `kind` (`string`, required, one of `"text"`, `"long-text"`, `"phone"`, `"choice"`, `"checkbox"`): `text`, `long-text`, `phone`, `choice` (one of `options`) or `checkbox`. - `label` (`string`, required, 1 to 120 characters) - `required` (`boolean`, required) - `options` (`string[]`, required, up to 12 items): The answers of a `choice` question, at least two. Empty for the other kinds. - `confirmation` (`string`, required, up to 1000 characters): Text shown to the guest after booking, and added to the confirmation email. - `redirectUrl` (`string`, required, up to 2000 characters): An `https://` page to send the guest to after booking, or empty. - `extraGuests` (`integer`, at least 0, at most 10, default `0`): How many other people a guest may add to a booking, 0 to 10. Each one gets the invitation and every later change. Defaults to 0, which hides the field. - `location` (`object`, required): Where the meeting happens. - `kind` (`string`, required, one of `"video"`, `"phone"`, `"in-person"`, `"none"`): `video` with a fixed link in `value`, `phone` (the guest is asked for a number), `in-person` with the address in `value`, or `none`. - `value` (`string`, required, up to 500 characters): The `https://` link of a `video` meeting or the address of an `in-person` one. - `availability` (`object`, required): When the page offers times, before the calendar is taken out. - `timezone` (`string`, required, 1 to 64 characters): The IANA time zone the hours below are read in. - `weekly` (`object[][]`, required, 7 to 7 items): Seven lists, Sunday first, of the hours open on that weekday. An empty list closes the day. - `start` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range opens, so `540` is 09:00. - `end` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range closes, later than `start`. - `overrides` (`object[]`, required, up to 180 items): Dates with their own hours, at most 180. `date` is `YYYY-MM-DD` in the time zone of the page, and an empty `ranges` closes that date. - `date` (`string`, required) - `ranges` (`object[]`, required, up to 6 items) - `start` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range opens, so `540` is 09:00. - `end` (`integer`, required, at least 0, at most 1440): Minutes after midnight the range closes, later than `start`. - `rules` (`object`, required): The limits on which of the open hours are offered. - `noticeMinutes` (`integer`, required, at least 0, at most 43200): How many minutes ahead a booking has to be made. - `horizonDays` (`integer`, required, at least 1, at most 365): How many days ahead the page offers times, up to 365. - `intervalMinutes` (`integer`, required, nullable): Minutes between two start times, one of 5, 10, 15, 20, 30, 45, 60, 90, 120. Null steps by the length of the meeting. - `bufferBeforeMinutes` (`integer`, required, at least 0, at most 240): Minutes kept free before every meeting, up to 240. - `bufferAfterMinutes` (`integer`, required, at least 0, at most 240): Minutes kept free after every meeting, up to 240. - `dailyLimit` (`integer`, required, nullable, at least 1, at most 50): The most bookings this page takes on one day, up to 50. Null for no limit. - `appearance` (`object`, required): How the public page looks. - `accent` (`string`, required, pattern `^#[0-9a-f]{6}$`): The colour of buttons and the picked day, as `#rrggbb`. - `theme` (`string`, required, one of `"auto"`, `"light"`, `"dark"`): `auto` follows the device of the guest, or force `light` or `dark`. - `showAvatar` (`boolean`, required) - `guestChanges` (`object`, required): What a guest may do from the link in their emails. - `cancel` (`boolean`, required) - `reschedule` (`boolean`, required) - `cutoffMinutes` (`integer`, required, at least 0, at most 20160): How many minutes before the meeting those changes close. - `busy` (`object`, required): What counts as busy besides the events the person made and the bookings they already have. - `addresses` (`string[]`, required, nullable, up to 50 items): The addresses whose invitations block time unless declined. Null checks every address the person holds. - `subscriptions` (`boolean`, required): Whether events from calendars the person subscribed to block time. - `outOfOffice` (`boolean`, default `true`): Whether the page offers no times while `fromEmail` is out of office. Defaults to true. - `seo` (`object`, default `{}`): How the public page presents itself to browsers and search engines. - `title` (`string`, up to 120 characters, default `""`): The title of the browser tab and of a search result. Empty uses the name of the page and the host. - `description` (`string`, up to 300 characters, default `""`): The summary under the title in a search result. Empty uses the start of the description. - `indexable` (`boolean`, default `false`): Whether search engines may list the page. False, the default, asks them not to. #### `BookingPageList` `object` - `object` (`string`, one of `"list"`) - `data` (`BookingPage[]`) #### `BookingTimes` `object` - `object` (`string`, required, one of `"booking_times"`) - `pageId` (`string`, required) - `timezone` (`string`, required): The time zone of the page. - `durationMinutes` (`integer`, required): The meeting length the times are for. - `times` (`string[]`, required): Every open start time in the window, in order. #### `DeletedBookingPage` `object` - `object` (`string`, required, one of `"booking_page"`) - `id` (`string`, required) - `deleted` (`boolean`, required, one of `true`)