Skip to the documentation
API

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/<slug>, 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

Scopescalendar:readReads

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.

Returns

200BookingPageList

The booking pages.

Errors

422

capability_unsupported: the key or app is limited to particular addresses.

The errors every operation can return400401403404500Error catalog

Also available in

TypeScript
bookings.listPages()
Python
bookings.list_pages()
Ruby
bookings.list_pages
PHP
bookings->listPages
Go
Bookings.ListPages
Java
bookings().listPages
C#
Bookings.ListPagesAsync
CLI
openemail bookings list-pages
MCP
listBookingPages

POST/booking-pages

Create a booking page

Scopescalendar:writeemails:sendChanges data

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.

Request body

namestringRequired

What the page is called, shown to guests as its heading, such as Intro call.

1 to 80 characters
slugstring

The last part of the public link, /book/<slug>: lowercase letters, digits and hyphens. Left out, it is made from the name. It is unique across OpenEmail.

1 to 60 characters
timezonestring

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.

1 to 64 characters
configobject

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.

descriptionstring

Text shown under the name of the page. Basic Markdown works: bold, italic, links and lists.

Up to 2000 characters
hostNamestring

The name guests see as the person they meet. Defaults to the name of the account.

Up to 80 characters
durationsinteger[]

The meeting lengths a guest can pick, in minutes, each a multiple of 5 between 5 and 720.

1 to 4 items
approvalboolean

True holds each new booking as a request until it is approved or declined. False confirms it at once.

fromEmailstring

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.

Up to 320 characters
notifyHostboolean

Whether that address gets an email about each new, moved or cancelled booking.

questionsobject[]

What the guest is asked besides their name and email, at most 10.

Up to 10 items
idstringRequired

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.

Pattern^[a-z0-9]{4,16}$
kindstringRequired

text, long-text, phone, choice (one of options) or checkbox.

One of"text""long-text""phone""choice""checkbox"
labelstringRequired
1 to 120 characters
requiredbooleanRequired
optionsstring[]Required

The answers of a choice question, at least two. Empty for the other kinds.

Up to 12 items
confirmationstring

Text shown to the guest after booking, and added to the confirmation email.

Up to 1000 characters
redirectUrlstring

An https:// page to send the guest to after booking, or empty.

Up to 2000 characters
extraGuestsinteger

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.

At least 0At most 10
locationobject

Where the meeting happens.

kindstring

video with a fixed link in value, phone (the guest is asked for a number), in-person with the address in value, or none.

One of"video""phone""in-person""none"
valuestring

The https:// link of a video meeting or the address of an in-person one.

Up to 500 characters
availabilityobject

When the page offers times, before the calendar is taken out.

timezonestring

The IANA time zone the hours below are read in.

1 to 64 characters
weeklyobject[][]

Seven lists, Sunday first, of the hours open on that weekday. An empty list closes the day.

7 to 7 items
startintegerRequired

Minutes after midnight the range opens, so 540 is 09:00.

At least 0At most 1440
endintegerRequired

Minutes after midnight the range closes, later than start.

At least 0At most 1440
overridesobject[]

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.

Up to 180 items
datestringRequired
rangesobject[]Required
Up to 6 items
startintegerRequired

Minutes after midnight the range opens, so 540 is 09:00.

At least 0At most 1440
endintegerRequired

Minutes after midnight the range closes, later than start.

At least 0At most 1440
rulesobject

The limits on which of the open hours are offered.

noticeMinutesinteger

How many minutes ahead a booking has to be made.

At least 0At most 43200
horizonDaysinteger

How many days ahead the page offers times, up to 365.

At least 1At most 365
intervalMinutesinteger

Minutes between two start times, one of 5, 10, 15, 20, 30, 45, 60, 90, 120. Null steps by the length of the meeting.

Can be null
bufferBeforeMinutesinteger

Minutes kept free before every meeting, up to 240.

At least 0At most 240
bufferAfterMinutesinteger

Minutes kept free after every meeting, up to 240.

At least 0At most 240
dailyLimitinteger

The most bookings this page takes on one day, up to 50. Null for no limit.

Can be nullAt least 1At most 50
appearanceobject

How the public page looks.

accentstring

The colour of buttons and the picked day, as #rrggbb.

Pattern^#[0-9a-f]{6}$
themestring

auto follows the device of the guest, or force light or dark.

One of"auto""light""dark"
showAvatarboolean
guestChangesobject

What a guest may do from the link in their emails.

cancelboolean
rescheduleboolean
cutoffMinutesinteger

How many minutes before the meeting those changes close.

At least 0At most 20160
busyobject

What counts as busy besides the events the person made and the bookings they already have.

addressesstring[]

The addresses whose invitations block time unless declined. Null checks every address the person holds.

Can be nullUp to 50 items
subscriptionsboolean

Whether events from calendars the person subscribed to block time.

outOfOfficeboolean

Whether the page offers no times while fromEmail is out of office. Defaults to true.

Defaulttrue
seoobject

How the public page presents itself to browsers and search engines.

titlestring

The title of the browser tab and of a search result. Empty uses the name of the page and the host.

Up to 120 charactersDefault""
descriptionstring

The summary under the title in a search result. Empty uses the start of the description.

Up to 300 charactersDefault""
indexableboolean

Whether search engines may list the page. False, the default, asks them not to.

Defaultfalse

Returns

201BookingPage

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 return400401404500Error catalog

Also available in

TypeScript
bookings.createPage()
Python
bookings.create_page()
Ruby
bookings.create_page
PHP
bookings->createPage
Go
Bookings.CreatePage
Java
bookings().createPage
C#
Bookings.CreatePageAsync
CLI
openemail bookings create-page
MCP
createBookingPage

GET/booking-pages/{id}

Read a booking page

Scopescalendar:readReads

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.

Path parameters

idstringRequired

The booking page, such as bkp_5c1e9a7b3d2f48e6a0b4c7d1, as GET /booking-pages lists it.

Returns

200BookingPage

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 return400401403500Error catalog

Also available in

TypeScript
bookings.getPage()
Python
bookings.get_page()
Ruby
bookings.get_page
PHP
bookings->getPage
Go
Bookings.GetPage
Java
bookings().getPage
C#
Bookings.GetPageAsync
CLI
openemail bookings get-page
MCP
getBookingPage

PATCH/booking-pages/{id}

Update a booking page

Scopescalendar:writeemails:sendChanges data

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.

Path parameters

idstringRequired

The booking page, such as bkp_5c1e9a7b3d2f48e6a0b4c7d1, as GET /booking-pages lists it.

Request body

namestring

What the page is called, shown to guests as its heading, such as Intro call.

1 to 80 characters
slugstring

The last part of the public link, /book/<slug>: lowercase letters, digits and hyphens. Left out, it is made from the name. It is unique across OpenEmail.

1 to 60 characters
statusstring

active takes bookings. paused keeps the link working but offers no times.

One of"active""paused"
configobject

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.

descriptionstring

Text shown under the name of the page. Basic Markdown works: bold, italic, links and lists.

Up to 2000 characters
hostNamestring

The name guests see as the person they meet. Defaults to the name of the account.

Up to 80 characters
durationsinteger[]

The meeting lengths a guest can pick, in minutes, each a multiple of 5 between 5 and 720.

1 to 4 items
approvalboolean

True holds each new booking as a request until it is approved or declined. False confirms it at once.

fromEmailstring

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.

Up to 320 characters
notifyHostboolean

Whether that address gets an email about each new, moved or cancelled booking.

questionsobject[]

What the guest is asked besides their name and email, at most 10.

Up to 10 items
idstringRequired

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.

Pattern^[a-z0-9]{4,16}$
kindstringRequired

text, long-text, phone, choice (one of options) or checkbox.

One of"text""long-text""phone""choice""checkbox"
labelstringRequired
1 to 120 characters
requiredbooleanRequired
optionsstring[]Required

The answers of a choice question, at least two. Empty for the other kinds.

Up to 12 items
confirmationstring

Text shown to the guest after booking, and added to the confirmation email.

Up to 1000 characters
redirectUrlstring

An https:// page to send the guest to after booking, or empty.

Up to 2000 characters
extraGuestsinteger

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.

At least 0At most 10
locationobject

Where the meeting happens.

kindstring

video with a fixed link in value, phone (the guest is asked for a number), in-person with the address in value, or none.

One of"video""phone""in-person""none"
valuestring

The https:// link of a video meeting or the address of an in-person one.

Up to 500 characters
availabilityobject

When the page offers times, before the calendar is taken out.

timezonestring

The IANA time zone the hours below are read in.

1 to 64 characters
weeklyobject[][]

Seven lists, Sunday first, of the hours open on that weekday. An empty list closes the day.

7 to 7 items
startintegerRequired

Minutes after midnight the range opens, so 540 is 09:00.

At least 0At most 1440
endintegerRequired

Minutes after midnight the range closes, later than start.

At least 0At most 1440
overridesobject[]

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.

Up to 180 items
datestringRequired
rangesobject[]Required
Up to 6 items
startintegerRequired

Minutes after midnight the range opens, so 540 is 09:00.

At least 0At most 1440
endintegerRequired

Minutes after midnight the range closes, later than start.

At least 0At most 1440
rulesobject

The limits on which of the open hours are offered.

noticeMinutesinteger

How many minutes ahead a booking has to be made.

At least 0At most 43200
horizonDaysinteger

How many days ahead the page offers times, up to 365.

At least 1At most 365
intervalMinutesinteger

Minutes between two start times, one of 5, 10, 15, 20, 30, 45, 60, 90, 120. Null steps by the length of the meeting.

Can be null
bufferBeforeMinutesinteger

Minutes kept free before every meeting, up to 240.

At least 0At most 240
bufferAfterMinutesinteger

Minutes kept free after every meeting, up to 240.

At least 0At most 240
dailyLimitinteger

The most bookings this page takes on one day, up to 50. Null for no limit.

Can be nullAt least 1At most 50
appearanceobject

How the public page looks.

accentstring

The colour of buttons and the picked day, as #rrggbb.

Pattern^#[0-9a-f]{6}$
themestring

auto follows the device of the guest, or force light or dark.

One of"auto""light""dark"
showAvatarboolean
guestChangesobject

What a guest may do from the link in their emails.

cancelboolean
rescheduleboolean
cutoffMinutesinteger

How many minutes before the meeting those changes close.

At least 0At most 20160
busyobject

What counts as busy besides the events the person made and the bookings they already have.

addressesstring[]

The addresses whose invitations block time unless declined. Null checks every address the person holds.

Can be nullUp to 50 items
subscriptionsboolean

Whether events from calendars the person subscribed to block time.

outOfOfficeboolean

Whether the page offers no times while fromEmail is out of office. Defaults to true.

Defaulttrue
seoobject

How the public page presents itself to browsers and search engines.

titlestring

The title of the browser tab and of a search result. Empty uses the name of the page and the host.

Up to 120 charactersDefault""
descriptionstring

The summary under the title in a search result. Empty uses the start of the description.

Up to 300 charactersDefault""
indexableboolean

Whether search engines may list the page. False, the default, asks them not to.

Defaultfalse

Returns

200BookingPage

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 return400401403500Error catalog

Also available in

TypeScript
bookings.updatePage()
Python
bookings.update_page()
Ruby
bookings.update_page
PHP
bookings->updatePage
Go
Bookings.UpdatePage
Java
bookings().updatePage
C#
Bookings.UpdatePageAsync
CLI
openemail bookings update-page
MCP
updateBookingPage

DELETE/booking-pages/{id}

Delete a booking page

Scopescalendar:writeDeletes

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.

Path parameters

idstringRequired

The booking page, such as bkp_5c1e9a7b3d2f48e6a0b4c7d1, as GET /booking-pages lists it.

Returns

200DeletedBookingPage

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 return400401403500Error catalog

Also available in

TypeScript
bookings.deletePage()
Python
bookings.delete_page()
Ruby
bookings.delete_page
PHP
bookings->deletePage
Go
Bookings.DeletePage
Java
bookings().deletePage
C#
Bookings.DeletePageAsync
CLI
openemail bookings delete-page
MCP
deleteBookingPage

GET/booking-pages/{id}/times

List the open times of a booking page

Scopescalendar:readReads

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.

Path parameters

idstringRequired

The booking page, such as bkp_5c1e9a7b3d2f48e6a0b4c7d1, as GET /booking-pages lists it.

Query parameters

fromstring

The start of the window. Defaults to now.

Formatdate-time
tostring

The end of the window, later than from. Defaults to 14 days after from, and counts for at most 62 days after it.

Formatdate-time
durationMinutesinteger

The meeting length in minutes, one of the durations of the page. Defaults to the shortest.

At least 1

Returns

200BookingTimes

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 return400401403500Error catalog

Also available in

TypeScript
bookings.listTimes()
Python
bookings.list_times()
Ruby
bookings.list_times
PHP
bookings->listTimes
Go
Bookings.ListTimes
Java
bookings().listTimes
C#
Bookings.ListTimesAsync
CLI
openemail bookings list-times

GET/bookings

List bookings

Scopescalendar:readReads

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.

Query parameters

viewstring

Which bookings to list: upcoming, pending, past or ended. Defaults to upcoming.

One of"upcoming""pending""past""ended"
pageIdstring

Only the bookings of this booking page, by its id. Left out, the bookings of every page of the person are listed.

1 to 64 characters
limitinteger

Page size, from 1 to 100. The server defaults to 30.

At least 1At most 100
cursorstring

The nextCursor of the previous page, passed back as it came. Leave it out for the first page.

1 to 256 characters

Returns

200BookingList

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 return401403500Error catalog

Also available in

TypeScript
bookings.list()bookings.listAll()bookings.iterate()
Python
bookings.list()bookings.list_all()bookings.iterate()
Ruby
bookings.listbookings.list_allbookings.iterate
PHP
bookings->listbookings->listAllbookings->iterate
Go
Bookings.ListBookings.ListAllBookings.Iterate
Java
bookings().listbookings().listAllbookings().iterate
C#
Bookings.ListAsyncBookings.ListAllAsyncBookings.IterateAsync
CLI
openemail bookings list
MCP
listBookings

GET/bookings/{id}

Read a booking

Scopescalendar:readReads

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.

Path parameters

idstringRequired

The booking, such as bkg_2b8d4f6a1c3e5079b6d8f0a2, as GET /bookings lists it.

Returns

200Booking

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 return400401403500Error catalog

Also available in

TypeScript
bookings.get()
Python
bookings.get()
Ruby
bookings.get
PHP
bookings->get
Go
Bookings.Get
Java
bookings().get
C#
Bookings.GetAsync
CLI
openemail bookings get
MCP
getBooking

POST/bookings/{id}/approve

Approve a booking

Scopescalendar:writeemails:sendSends mail

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.

Path parameters

idstringRequired

The booking, such as bkg_2b8d4f6a1c3e5079b6d8f0a2, as GET /bookings lists it.

Returns

200Booking

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 return400401403500Error catalog

Also available in

TypeScript
bookings.approve()
Python
bookings.approve()
Ruby
bookings.approve
PHP
bookings->approve
Go
Bookings.Approve
Java
bookings().approve
C#
Bookings.ApproveAsync
CLI
openemail bookings approve
MCP
approveBooking

POST/bookings/{id}/decline

Decline a booking

Scopescalendar:writeemails:sendSends mail

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.

Path parameters

idstringRequired

The booking, such as bkg_2b8d4f6a1c3e5079b6d8f0a2, as GET /bookings lists it.

Request body

reasonstring

A sentence for the guest, at most 500 characters, included in the email they get.

Can be nullUp to 500 characters

Returns

200Booking

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 return400401403500Error catalog

Also available in

TypeScript
bookings.decline()
Python
bookings.decline()
Ruby
bookings.decline
PHP
bookings->decline
Go
Bookings.Decline
Java
bookings().decline
C#
Bookings.DeclineAsync
CLI
openemail bookings decline
MCP
declineBooking

POST/bookings/{id}/cancel

Cancel a booking

Scopescalendar:writeemails:sendSends mail

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.

Path parameters

idstringRequired

The booking, such as bkg_2b8d4f6a1c3e5079b6d8f0a2, as GET /bookings lists it.

Request body

reasonstring

A sentence for the guest, at most 500 characters, included in the email they get.

Can be nullUp to 500 characters

Returns

200Booking

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 return400401403500Error catalog

Also available in

TypeScript
bookings.cancel()
Python
bookings.cancel()
Ruby
bookings.cancel
PHP
bookings->cancel
Go
Bookings.Cancel
Java
bookings().cancel
C#
Bookings.CancelAsync
CLI
openemail bookings cancel
MCP
cancelBooking

POST/bookings/{id}/resend

Send the booking email again

Scopescalendar:writeemails:sendSends mail

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.

Path parameters

idstringRequired

The booking, such as bkg_2b8d4f6a1c3e5079b6d8f0a2, as GET /bookings lists it.

Returns

200Booking

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 return400401403500Error catalog

Also available in

TypeScript
bookings.resendEmail()
Python
bookings.resend_email()
Ruby
bookings.resend_email
PHP
bookings->resendEmail
Go
Bookings.ResendEmail
Java
bookings().resendEmail
C#
Bookings.ResendEmailAsync
CLI
openemail bookings resend-email
MCP
resendBookingEmail

Objects

Bookingobject

objectstringRequired
One of"booking"
idstringRequired

The id, which starts with bkg_.

pageIdstringRequired

The booking page it was made on.

pageNamestringRequired
statusstringRequired

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.

One of"pending""confirmed""declined""cancelled"
expiredbooleanRequired

True for a request nobody answered before its time came.

pastbooleanRequired

True once the meeting is over.

startstringRequired

When the meeting starts.

Formatdate-time
endstringRequired

When it ends.

Formatdate-time
durationMinutesintegerRequired
guestobjectRequired
namestringRequired
emailstringRequired
Formatemail
timezonestringRequired

The time zone the guest booked in, which their emails use.

guestsstring[]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.

answersobject[]Required

What the guest answered to the questions of the page.

idstringRequired

The id of the question.

labelstringRequired

The question as it was asked.

kindstringRequired
One of"text""long-text""phone""choice""checkbox"
valuestringRequired

The answer. A checkbox answers yes or no.

locationstringRequired

Where the meeting happens, as the guest was told: the link, the phone number or the address.

eventIdstringRequired

The calendar event of the booking, as GET /calendar/events/{id} reads it. Null once the booking ended and its event was removed.

Can be null
endedBystringRequired

Who declined or cancelled it.

Can be nullOne of"host""guest"
endReasonstringRequired

The reason they gave.

Can be null
rescheduleCountintegerRequired

How often the meeting was moved.

At least 0
guestMailFailedbooleanRequired

True when the last email to the guest could not be sent. POST /bookings/{id}/resend tries again.

createdAtstringRequired

When the guest booked.

Formatdate-time

BookingListobject

objectstring
One of"list"
dataBooking[]
hasMoreboolean

True when another page follows. Pass nextCursor back as cursor to read it.

nextCursorstring

An opaque cursor for the next page, or null on the last page. Pass it back unchanged.

Can be null

BookingPageobject

objectstringRequired
One of"booking_page"
idstringRequired

The id, which starts with bkp_.

slugstringRequired

The last part of the public link, /book/<slug>: lowercase letters, digits and hyphens. Left out, it is made from the name. It is unique across OpenEmail.

namestringRequired

What the page is called, shown to guests as its heading, such as Intro call.

statusstringRequired

active takes bookings. paused keeps the link working but offers no times.

One of"active""paused"
urlstringRequired

The public link to hand to guests.

problemstringRequired

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.

Can be nullOne of"sender""host""hours"
configBookingPageConfigRequired
countsobjectRequired
upcomingintegerRequired

Confirmed bookings that have not started.

At least 0
pendingintegerRequired

Bookings that wait for approval.

At least 0
awayobject[]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.

addressstringRequired

The address, or the catch-all such as *@example.com, that is out of office.

startsAtstringRequired

When the period starts.

Formatdate-time
endsAtstringRequired

When it ends, or null while it has no end date.

Can be nullFormatdate-time
createdAtstringRequired

When the page was created.

Formatdate-time
updatedAtstringRequired

When the page last changed.

Formatdate-time

BookingPageConfigobject

descriptionstringRequired

Text shown under the name of the page. Basic Markdown works: bold, italic, links and lists.

Up to 2000 characters
hostNamestringRequired

The name guests see as the person they meet. Defaults to the name of the account.

Up to 80 characters
durationsinteger[]Required

The meeting lengths a guest can pick, in minutes, each a multiple of 5 between 5 and 720.

1 to 4 items
approvalbooleanRequired

True holds each new booking as a request until it is approved or declined. False confirms it at once.

fromEmailstringRequired

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.

Up to 320 characters
notifyHostbooleanRequired

Whether that address gets an email about each new, moved or cancelled booking.

questionsobject[]Required

What the guest is asked besides their name and email, at most 10.

Up to 10 items
idstringRequired

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.

Pattern^[a-z0-9]{4,16}$
kindstringRequired

text, long-text, phone, choice (one of options) or checkbox.

One of"text""long-text""phone""choice""checkbox"
labelstringRequired
1 to 120 characters
requiredbooleanRequired
optionsstring[]Required

The answers of a choice question, at least two. Empty for the other kinds.

Up to 12 items
confirmationstringRequired

Text shown to the guest after booking, and added to the confirmation email.

Up to 1000 characters
redirectUrlstringRequired

An https:// page to send the guest to after booking, or empty.

Up to 2000 characters
extraGuestsinteger

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.

At least 0At most 10Default0
locationobjectRequired

Where the meeting happens.

kindstringRequired

video with a fixed link in value, phone (the guest is asked for a number), in-person with the address in value, or none.

One of"video""phone""in-person""none"
valuestringRequired

The https:// link of a video meeting or the address of an in-person one.

Up to 500 characters
availabilityobjectRequired

When the page offers times, before the calendar is taken out.

timezonestringRequired

The IANA time zone the hours below are read in.

1 to 64 characters
weeklyobject[][]Required

Seven lists, Sunday first, of the hours open on that weekday. An empty list closes the day.

7 to 7 items
startintegerRequired

Minutes after midnight the range opens, so 540 is 09:00.

At least 0At most 1440
endintegerRequired

Minutes after midnight the range closes, later than start.

At least 0At most 1440
overridesobject[]Required

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.

Up to 180 items
datestringRequired
rangesobject[]Required
Up to 6 items
startintegerRequired

Minutes after midnight the range opens, so 540 is 09:00.

At least 0At most 1440
endintegerRequired

Minutes after midnight the range closes, later than start.

At least 0At most 1440
rulesobjectRequired

The limits on which of the open hours are offered.

noticeMinutesintegerRequired

How many minutes ahead a booking has to be made.

At least 0At most 43200
horizonDaysintegerRequired

How many days ahead the page offers times, up to 365.

At least 1At most 365
intervalMinutesintegerRequired

Minutes between two start times, one of 5, 10, 15, 20, 30, 45, 60, 90, 120. Null steps by the length of the meeting.

Can be null
bufferBeforeMinutesintegerRequired

Minutes kept free before every meeting, up to 240.

At least 0At most 240
bufferAfterMinutesintegerRequired

Minutes kept free after every meeting, up to 240.

At least 0At most 240
dailyLimitintegerRequired

The most bookings this page takes on one day, up to 50. Null for no limit.

Can be nullAt least 1At most 50
appearanceobjectRequired

How the public page looks.

accentstringRequired

The colour of buttons and the picked day, as #rrggbb.

Pattern^#[0-9a-f]{6}$
themestringRequired

auto follows the device of the guest, or force light or dark.

One of"auto""light""dark"
showAvatarbooleanRequired
guestChangesobjectRequired

What a guest may do from the link in their emails.

cancelbooleanRequired
reschedulebooleanRequired
cutoffMinutesintegerRequired

How many minutes before the meeting those changes close.

At least 0At most 20160
busyobjectRequired

What counts as busy besides the events the person made and the bookings they already have.

addressesstring[]Required

The addresses whose invitations block time unless declined. Null checks every address the person holds.

Can be nullUp to 50 items
subscriptionsbooleanRequired

Whether events from calendars the person subscribed to block time.

outOfOfficeboolean

Whether the page offers no times while fromEmail is out of office. Defaults to true.

Defaulttrue
seoobject

How the public page presents itself to browsers and search engines.

Default{}
titlestring

The title of the browser tab and of a search result. Empty uses the name of the page and the host.

Up to 120 charactersDefault""
descriptionstring

The summary under the title in a search result. Empty uses the start of the description.

Up to 300 charactersDefault""
indexableboolean

Whether search engines may list the page. False, the default, asks them not to.

Defaultfalse

BookingTimesobject

objectstringRequired
One of"booking_times"
pageIdstringRequired
timezonestringRequired

The time zone of the page.

durationMinutesintegerRequired

The meeting length the times are for.

timesstring[]Required

Every open start time in the window, in order.

DeletedBookingPageobject

objectstringRequired
One of"booking_page"
idstringRequired
deletedbooleanRequired
One oftrue

Your inbox,
on your own terms.

Open mailGet Started
Products
BusinessDevelopersAI & agentsPersonal
OpenEmail
PricingFeaturesDownloadCompareMigrateCustomersSecurity and scaleAboutContactPrivacy PolicyTerms of ServiceUptime guarantee
Resources
DocumentationAPI referenceTypeScript SDKPython SDKRuby SDKPHP SDKGo SDKJava SDKC# SDKCommand lineMCP serverEmail templatesConnectorsUse casesStatus
Tools
AI template generatorDeliverability checkerBIMI logo checkerEmail address checkerTemporary email addressDMARC record generatorEmail cost calculator
© 2026 OpenEmail. All rights reserved.