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.
/booking-pages/booking-pages/booking-pages/{id}/booking-pages/{id}/booking-pages/{id}/booking-pages/{id}/background/booking-pages/{id}/background/booking-pages/{id}/times/bookings/bookings/{id}/bookings/{id}/approve/bookings/{id}/decline/bookings/{id}/cancel/bookings/{id}/reschedule/bookings/{id}/resend/bookings/analytics
GET/booking-pages
List booking pages
Every booking page of the person, oldest first unless sort says otherwise, each with its settings, its public link and how many bookings are upcoming or wait for approval. q, status, since and until narrow the list. 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.
Query parameters
qstringOnly the pages whose name or link contains this text, at most 200 characters. Case and accents are ignored.
Up to 200 charactersstatusstringactivefor the pages that take bookings,pausedfor the ones that do not. Left out, both.One of"active""paused"sincestringOnly the pages made at or after this instant, as a
Dateor an ISO 8601 string.Formatdate-timeuntilstringOnly the pages made before this instant, later than
since.Formatdate-timesortstringoldest(the default) ornewestby when the page was made,namefrom A to Z, orupcomingwith the most upcoming meetings first.One of"oldest""newest""name""upcoming"
Returns
The booking pages.
Errors
- 422
invalid_parameter: a query value is malformed, oruntilis not later thansince.capability_unsupported: the key or app is limited to particular addresses.
The errors every operation can return400401403404429500Error catalog
Also available in
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.
Request body
namestringRequiredWhat the page is called, shown to guests as its heading, such as
Intro call.1 to 80 charactersslugstringThe 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 Nextmail.1 to 60 characterstimezonestringThe IANA time zone the working hours are read in, such as
Europe/Berlin, for a new page whoseconfig.availability.timezoneis not sent. Defaults toUTC.1 to 64 charactersconfigobjectThe 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,busyandseoeach field is merged on its own. A list (durations,questions,availability.weekly,availability.overrides) is replaced whole.descriptionstringText shown under the name of the page. Basic Markdown works: bold, italic, links and lists.
Up to 2000 charactershostNamestringThe name guests see as the person they meet. Defaults to the name of the account.
Up to 80 charactersdurationsinteger[]The meeting lengths a guest can pick, in minutes, each a multiple of 5 between 5 and 720.
1 to 4 itemsapprovalbooleanTrue holds each new booking as a request until it is approved or declined. False confirms it at once.
fromEmailstringThe 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 charactersnotifyHostbooleanWhether 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 itemsidstringRequiredA stable key for the answers: 4 to 16 lowercase letters and digits, unique on the page.
name,email,phone,timezoneandstartare taken.Pattern^[a-z0-9]{4,16}$kindstringRequiredtext,long-text,phone,choice(one ofoptions) orcheckbox.One of"text""long-text""phone""choice""checkbox"labelstringRequired- 1 to 120 characters
requiredbooleanRequiredoptionsstring[]RequiredThe answers of a
choicequestion, at least two. Empty for the other kinds.Up to 12 itemsplaceholderstringExample text shown in the empty field of a
text,long-textorphonequestion, such asAnything we should know before the meeting?. Up to 160 characters, empty for none. Achoiceorcheckboxquestion ignores it.Up to 160 characters
confirmationstringText shown to the guest after booking, and added to the confirmation email.
Up to 1000 charactersredirectUrlstringAn
https://page to send the guest to after booking, or empty.Up to 2000 charactersextraGuestsintegerHow 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 10remindersobjectWhen the guest is emailed a reminder and when the host is reminded, each a list of minutes before the start.
guestinteger[]Minutes before the start to email the guest a reminder, at most 3, each one of 10, 30, 60, 120, 1440, 2880, 10080. Defaults to one day before. An empty list sends none.
Up to 3 itemshostinteger[]Minutes before the start the host is reminded by the alarm on the meeting in their calendar, at most 3, each one of 0, 5, 10, 15, 30, 60, 1440. Defaults to 10. It applies to meetings booked after it changes.
Up to 3 items
locationobjectWhere the meeting happens.
kindstringvideowith a fixed link invalue,phone(the guest is asked for a number),in-personwith the address invalue, ornone.One of"video""phone""in-person""none"valuestringThe
https://link of avideomeeting or the address of anin-personone.Up to 500 characters
availabilityobjectWhen the page offers times, before the calendar is taken out.
timezonestringThe IANA time zone the hours below are read in.
1 to 64 charactersweeklyobject[][]Seven lists, Sunday first, of the hours open on that weekday. An empty list closes the day.
7 to 7 itemsstartintegerRequiredMinutes after midnight the range opens, so
540is 09:00.At least 0At most 1440endintegerRequiredMinutes after midnight the range closes, later than
start.At least 0At most 1440
overridesobject[]Dates with their own hours, at most 180.
dateisYYYY-MM-DDin the time zone of the page, and an emptyrangescloses that date.Up to 180 itemsdatestringRequiredrangesobject[]Required- Up to 6 items
startintegerRequiredMinutes after midnight the range opens, so
540is 09:00.At least 0At most 1440endintegerRequiredMinutes after midnight the range closes, later than
start.At least 0At most 1440
rulesobjectThe limits on which of the open hours are offered.
noticeMinutesintegerHow many minutes ahead a booking has to be made.
At least 0At most 43200horizonDaysintegerHow many days ahead the page offers times, up to 365.
At least 1At most 365intervalMinutesintegerMinutes 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 nullbufferBeforeMinutesintegerMinutes kept free before every meeting, up to 240.
At least 0At most 240bufferAfterMinutesintegerMinutes kept free after every meeting, up to 240.
At least 0At most 240dailyLimitintegerThe most bookings this page takes on one day, up to 50. Null for no limit.
Can be nullAt least 1At most 50
appearanceobjectHow the public page looks.
accentstringThe colour of buttons and the picked day, as
#rrggbb.Pattern^#[0-9a-f]{6}$themestringautofollows the device of the guest, or forcelightordark.One of"auto""light""dark"showAvatarbooleanbackgroundstringWhat fills the page behind the card:
default, one of the presetsdusk,mist,sand,night,meadow,dots,brush,trail,ember,canvas,bloom,field,wandererandgold,imagefor the uploaded background image, or a colour as#rrggbb. Defaults todefault.Default"default"fontsobjectThe typefaces of the public page:
primaryfor its text andsecondaryfor its title. Each is one of the brand fonts the workspace appearance offers, or null for the standard font.Default{"primary":null,"secondary":null}primarystringThe font of the text, such as
inter. Null uses the standard font.Can be nullOne of"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"DefaultnullsecondarystringThe font of the title, such as
instrument-serif. Null keeps the title in the font of the text.Can be nullOne of"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"Defaultnull
backgroundImagestringThe address of the uploaded background image, or null. Read only: upload one with
PUT /booking-pages/{id}/backgroundand remove it withDELETEon the same path.Can be nullUp to 2000 charactersDefaultnull
guestChangesobjectWhat a guest may do from the link in their emails.
cancelbooleanreschedulebooleancutoffMinutesintegerHow many minutes before the meeting those changes close.
At least 0At most 20160
busyobjectWhat 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 itemssubscriptionsbooleanWhether events from calendars the person subscribed to block time.
outOfOfficebooleanWhether the page offers no times while
fromEmailis out of office. Defaults to true.Defaulttrue
seoobjectHow the public page presents itself to browsers and search engines.
titlestringThe title of the browser tab and of a search result. Empty uses the name of the page and the host.
Up to 120 charactersDefault""descriptionstringThe summary under the title in a search result. Empty uses the start of the description.
Up to 300 charactersDefault""indexablebooleanWhether search engines may list the page. False, the default, asks them not to.
Defaultfalse
Returns
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 thatslug.- 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 return400401404429500Error catalog
Also available in
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.
Path parameters
idstringRequiredThe booking page, such as
bkp_5c1e9a7b3d2f48e6a0b4c7d1, asGET /booking-pageslists it.
Returns
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 return400401403429500Error catalog
Also available in
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.
Path parameters
idstringRequiredThe booking page, such as
bkp_5c1e9a7b3d2f48e6a0b4c7d1, asGET /booking-pageslists it.
Request body
namestringWhat the page is called, shown to guests as its heading, such as
Intro call.1 to 80 charactersslugstringThe last part of the public link,
/book/<slug>: lowercase letters, digits and hyphens. It is unique across Nextmail. Left out, the stored link stays.1 to 60 charactersstatusstringactivetakes bookings.pausedkeeps the link working but offers no times.One of"active""paused"configobjectThe 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,busyandseoeach field is merged on its own. A list (durations,questions,availability.weekly,availability.overrides) is replaced whole.descriptionstringText shown under the name of the page. Basic Markdown works: bold, italic, links and lists.
Up to 2000 charactershostNamestringThe name guests see as the person they meet. Left out, the stored name stays.
Up to 80 charactersdurationsinteger[]The meeting lengths a guest can pick, in minutes, each a multiple of 5 between 5 and 720.
1 to 4 itemsapprovalbooleanTrue holds each new booking as a request until it is approved or declined. False confirms it at once.
fromEmailstringThe 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 charactersnotifyHostbooleanWhether 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 itemsidstringRequiredA stable key for the answers: 4 to 16 lowercase letters and digits, unique on the page.
name,email,phone,timezoneandstartare taken.Pattern^[a-z0-9]{4,16}$kindstringRequiredtext,long-text,phone,choice(one ofoptions) orcheckbox.One of"text""long-text""phone""choice""checkbox"labelstringRequired- 1 to 120 characters
requiredbooleanRequiredoptionsstring[]RequiredThe answers of a
choicequestion, at least two. Empty for the other kinds.Up to 12 itemsplaceholderstringExample text shown in the empty field of a
text,long-textorphonequestion, such asAnything we should know before the meeting?. Up to 160 characters, empty for none. Achoiceorcheckboxquestion ignores it.Up to 160 characters
confirmationstringText shown to the guest after booking, and added to the confirmation email.
Up to 1000 charactersredirectUrlstringAn
https://page to send the guest to after booking, or empty.Up to 2000 charactersextraGuestsintegerHow many other people a guest may add to a booking, 0 to 10. Each one gets the invitation and every later change, and 0 hides the field. Left out, the stored number stays.
At least 0At most 10remindersobjectWhen the guest is emailed a reminder and when the host is reminded, each a list of minutes before the start.
guestinteger[]Minutes before the start to email the guest a reminder, at most 3, each one of 10, 30, 60, 120, 1440, 2880, 10080. An empty list sends none. Left out, the stored list stays.
Up to 3 itemshostinteger[]Minutes before the start the host is reminded by the alarm on the meeting in their calendar, at most 3, each one of 0, 5, 10, 15, 30, 60, 1440. It applies to meetings booked after it changes. Left out, the stored list stays.
Up to 3 items
locationobjectWhere the meeting happens.
kindstringvideowith a fixed link invalue,phone(the guest is asked for a number),in-personwith the address invalue, ornone.One of"video""phone""in-person""none"valuestringThe
https://link of avideomeeting or the address of anin-personone.Up to 500 characters
availabilityobjectWhen the page offers times, before the calendar is taken out.
timezonestringThe IANA time zone the hours below are read in.
1 to 64 charactersweeklyobject[][]Seven lists, Sunday first, of the hours open on that weekday. An empty list closes the day.
7 to 7 itemsstartintegerRequiredMinutes after midnight the range opens, so
540is 09:00.At least 0At most 1440endintegerRequiredMinutes after midnight the range closes, later than
start.At least 0At most 1440
overridesobject[]Dates with their own hours, at most 180.
dateisYYYY-MM-DDin the time zone of the page, and an emptyrangescloses that date.Up to 180 itemsdatestringRequiredrangesobject[]Required- Up to 6 items
startintegerRequiredMinutes after midnight the range opens, so
540is 09:00.At least 0At most 1440endintegerRequiredMinutes after midnight the range closes, later than
start.At least 0At most 1440
rulesobjectThe limits on which of the open hours are offered.
noticeMinutesintegerHow many minutes ahead a booking has to be made.
At least 0At most 43200horizonDaysintegerHow many days ahead the page offers times, up to 365.
At least 1At most 365intervalMinutesintegerMinutes 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 nullbufferBeforeMinutesintegerMinutes kept free before every meeting, up to 240.
At least 0At most 240bufferAfterMinutesintegerMinutes kept free after every meeting, up to 240.
At least 0At most 240dailyLimitintegerThe most bookings this page takes on one day, up to 50. Null for no limit.
Can be nullAt least 1At most 50
appearanceobjectHow the public page looks.
accentstringThe colour of buttons and the picked day, as
#rrggbb.Pattern^#[0-9a-f]{6}$themestringautofollows the device of the guest, or forcelightordark.One of"auto""light""dark"showAvatarbooleanbackgroundstringWhat fills the page behind the card:
default, one of the presetsdusk,mist,sand,night,meadow,dots,brush,trail,ember,canvas,bloom,field,wandererandgold,imagefor the uploaded background image, or a colour as#rrggbb. Left out, the stored background stays.fontsobjectThe typefaces of the public page, merged by key:
primaryfor its text andsecondaryfor its title, each a brand font or null for the standard font. Left out, the stored fonts stay.primarystringThe font of the text, such as
inter. Null uses the standard font.Can be nullOne of"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"secondarystringThe font of the title, such as
instrument-serif. Null keeps the title in the font of the text.Can be nullOne of"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"
backgroundImagestringRead only. Sending it back as you read it changes nothing; upload or remove the image on the background path of the page.
Can be nullUp to 2000 characters
guestChangesobjectWhat a guest may do from the link in their emails.
cancelbooleanreschedulebooleancutoffMinutesintegerHow many minutes before the meeting those changes close.
At least 0At most 20160
busyobjectWhat 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 itemssubscriptionsbooleanWhether events from calendars the person subscribed to block time.
outOfOfficebooleanWhether the page offers no times while
fromEmailis out of office. Left out, the stored setting stays.
seoobjectHow the public page presents itself to browsers and search engines.
titlestringThe title of the browser tab and of a search result. Empty uses the name of the page and the host.
Up to 120 charactersdescriptionstringThe summary under the title in a search result. Empty uses the start of the description.
Up to 300 charactersindexablebooleanWhether search engines may list the page. False asks them not to. Left out, the stored setting stays.
Returns
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 thatslug.- 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 return400401403429500Error catalog
Also available in
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.
Path parameters
idstringRequiredThe booking page, such as
bkp_5c1e9a7b3d2f48e6a0b4c7d1, asGET /booking-pageslists it.
Returns
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 return400401403429500Error catalog
Also available in
PUT/booking-pages/{id}/background
Upload the background image of a booking page
Uploads the photo that fills the public page behind the card, replacing the one there was, and switches config.appearance.background to image. Send the image itself as the body, not JSON, with its type in Content-Type. Up to 5 MB goes in; it is fitted and stored as WebP, and config.appearance.backgroundImage then holds its address. An animated image keeps its first frame.
Requires the calendar:write and emails:send scopes.
Path parameters
idstringRequiredThe booking page, such as
bkp_5c1e9a7b3d2f48e6a0b4c7d1, asGET /booking-pageslists it.
Request body
Content typeimage/png, image/jpeg, image/webp, image/gif
Returns
The page, showing the new image.
Errors
- 404
booking_page_not_found: the person has no booking page with that id.- 422
invalid_imagewhen the body is not an image of an accepted type, is too large or cannot be read.capability_unsupported: the key or app is limited to particular addresses.- 502
image_not_stored: the image was read but could not be stored. Try again.- 503
image_busy: the image service is saturated. Try again shortly.
The errors every operation can return400401403429500Error catalog
Also available in
DELETE/booking-pages/{id}/background
Remove the background image of a booking page
Deletes the stored background photo of a page. A page that showed it goes back to the default background, and one that showed a preset or a colour keeps it. Removing an image that is not set changes nothing, so a repeated call is safe.
Requires the calendar:write and emails:send scopes.
Path parameters
idstringRequiredThe booking page, such as
bkp_5c1e9a7b3d2f48e6a0b4c7d1, asGET /booking-pageslists it.
Returns
The page, without the image.
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 return400401403429500Error catalog
Also available in
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. With bookingId they are the times that booking can move to with POST /bookings/{id}/reschedule.
Requires the calendar:read scope.
Path parameters
idstringRequiredThe booking page, such as
bkp_5c1e9a7b3d2f48e6a0b4c7d1, asGET /booking-pageslists it.
Query parameters
fromstringThe start of the window. Defaults to now.
Formatdate-timetostringThe end of the window, later than
from. Defaults to 14 days afterfrom, and counts for at most 62 days after it.Formatdate-timedurationMinutesintegerThe meeting length in minutes, one of the
durationsof the page. Defaults to the shortest.At least 1bookingIdstringA booking on this page to find a new time for, such as
bkg_2b8d4f6a1c3e5079b6d8f0a2. Its own time counts as free and the times are for its length, sodurationMinutesis ignored.1 to 64 characters
Returns
The open times.
Errors
- 404
booking_page_not_found: the person has no booking page with that id.booking_not_found: the person has no booking with that id.- 409
booking_ended: the booking was already declined or cancelled.- 422
invalid_parameter:tois not later thanfrom, ordurationMinutesis not a length the page offers.capability_unsupported: the key or app is limited to particular addresses.
The errors every operation can return400401403429500Error catalog
Also available in
GET/bookings
List bookings
The meetings guests booked on the pages of the person, or on some of them with pageIds. q searches the guest and the page, and from and to keep the meetings that start in a window. 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
viewstringWhich bookings to list:
upcoming,pending,pastorended. Defaults toupcoming.One of"upcoming""pending""past""ended"pageIdstringOnly the bookings of this booking page, by its id. Left out, the bookings of every page of the person are listed.
1 to 64 characterspageIdsstringOnly the bookings of these booking pages, at most 25 ids. Left out, every page of the person.
Up to 1625 charactersqstringOnly the bookings whose guest name, guest email or page name contains this text, at most 200 characters. Case and accents are ignored.
Up to 200 charactersfromstringOnly the meetings that start at or after this instant, as a
Dateor an ISO 8601 string.Formatdate-timetostringOnly the meetings that start before this instant, later than
from.Formatdate-timelimitintegerPage size, from 1 to 100. The server defaults to 30.
At least 1At most 100cursorstringThe
nextCursorof the previous page, passed back as it came. Leave it out for the first page.1 to 256 characters
Returns
A page of bookings.
Errors
- 400
- 404
booking_page_not_found: the person has no booking page with that id.- 422
invalid_parameter: a query value is malformed,pageIdsnames too many pages, ortois not later thanfrom.capability_unsupported: the key or app is limited to particular addresses.
The errors every operation can return401403429500Error catalog
Also available in
- TypeScript
nextmail.bookings.list()nextmail.bookings.listAll()nextmail.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
nextmail bookings list- MCP
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.
Path parameters
idstringRequiredThe booking, such as
bkg_2b8d4f6a1c3e5079b6d8f0a2, asGET /bookingslists it.
Returns
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 return400401403429500Error catalog
Also available in
- TypeScript
nextmail.bookings.get()- Python
bookings.get()- Ruby
bookings.get- PHP
bookings->get- Go
Bookings.Get- Java
bookings().get- C#
Bookings.GetAsync- CLI
nextmail bookings get- MCP
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.
Path parameters
idstringRequiredThe booking, such as
bkg_2b8d4f6a1c3e5079b6d8f0a2, asGET /bookingslists it.
Returns
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 return400401403429500Error catalog
Also available in
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.
Path parameters
idstringRequiredThe booking, such as
bkg_2b8d4f6a1c3e5079b6d8f0a2, asGET /bookingslists it.
Request body
reasonstringA sentence for the guest, at most 500 characters, included in the email they get.
Can be nullUp to 500 characters
Returns
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 return400401403429500Error catalog
Also available in
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.
Path parameters
idstringRequiredThe booking, such as
bkg_2b8d4f6a1c3e5079b6d8f0a2, asGET /bookingslists it.
Request body
reasonstringA sentence for the guest, at most 500 characters, included in the email they get.
Can be nullUp to 500 characters
Returns
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 return400401403429500Error catalog
Also available in
POST/bookings/{id}/reschedule
Reschedule a booking
Moves a meeting that has not started to a new time, keeping its length, and moves its calendar event with it. The time has to be open on the page, as GET /booking-pages/{id}/times lists the times with bookingId; the page may be paused, and the cut-off for guests does not apply to you. A booking that waits for approval is confirmed at the new time. The guest is told by email, sent from the address of the page with the calendar invitation or its cancellation attached. You get a copy too, unless config.notifyHost is false.
Requires the calendar:write and emails:send scopes.
Path parameters
idstringRequiredThe booking, such as
bkg_2b8d4f6a1c3e5079b6d8f0a2, asGET /bookingslists it.
Request body
startstringRequiredThe new start as an ISO 8601 instant. It has to be one of the open times of the page for this booking, as
GET /booking-pages/{id}/timeslists them withbookingId. The meeting keeps its length.Formatdate-timereasonstringA sentence for the guest, at most 500 characters, included in the email about the new time.
Can be nullUp to 500 characters
Returns
The booking at its new time.
Errors
- 404
booking_not_found: the person has no booking with that id.- 409
booking_time_unavailable: that time is not open on the page for this booking.booking_ended: the booking was declined or cancelled, or the meeting has started.- 422
invalid_parameter:startis missing or malformed.capability_unsupported: the key or app is limited to particular addresses.
The errors every operation can return400401403429500Error catalog
Also available in
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.
Path parameters
idstringRequiredThe booking, such as
bkg_2b8d4f6a1c3e5079b6d8f0a2, asGET /bookingslists it.
Returns
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 return400401403429500Error catalog
Also available in
GET/bookings/analytics
Read booking analytics
The numbers behind the Analytics tabs of Booking: the bookings guests made over a window, what became of them, the pages and weekdays they went to, and the meetings still to come right now, for every page of the person or for the pages pageIds names. A booking counts in the window it was made in, whatever its meeting time. 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.
Query parameters
pageIdstringCount only the bookings of this booking page, such as
bkp_5c1e9a7b3d2f48e6a0b4c7d1, the same aspageIdswith one id.1 to 64 characterspageIdsstringCount only these booking pages, at most 25, such as
['bkp_5c1e9a7b3d2f48e6a0b4c7d1']. Every page of the person when left out.Up to 1625 charactersdaysintegerHow far back to look, from 1 to 1095, defaulting to 30.
At least 1At most 1095minutesintegerThe window in minutes, from 1 to 1576800, which wins over
dayswhen both are sent.At least 1At most 1576800grainstringBucket width:
minute,hourorday, defaulting today.One of"minute""hour""day"offsetMinutesintegerMinutes east of UTC to cut the buckets and the weekdays in, from -840 to 840, defaulting to 0. Pass
-new Date().getTimezoneOffset()for the local zone.At least -840At most 840
Returns
The window, the totals and the breakdowns.
Errors
- 404
booking_page_not_found: the person has no booking page with that id.- 422
invalid_parameter: a query value is out of range, orpageIdsnames too many pages.capability_unsupported: the key or app is limited to particular addresses.
The errors every operation can return400401403429500Error catalog
Also available in
Objects
Bookingobject
objectstringRequired- One of
"booking" idstringRequiredThe id, which starts with
bkg_.pageIdstringRequiredThe booking page it was made on.
pageNamestringRequiredstatusstringRequiredpendingwhile it waits for approval,confirmedonce the meeting stands,declinedwhen a request was turned down, andcancelledwhen a confirmed meeting was called off.One of"pending""confirmed""declined""cancelled"expiredbooleanRequiredTrue for a request nobody answered before its time came.
pastbooleanRequiredTrue once the meeting is over.
startstringRequiredWhen the meeting starts.
Formatdate-timeendstringRequiredWhen it ends.
Formatdate-timedurationMinutesintegerRequiredguestobjectRequirednamestringRequiredemailstringRequired- Format
email timezonestringRequiredThe time zone the guest booked in, which their emails use.
guestsstring[]RequiredThe 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[]RequiredWhat the guest answered to the questions of the page.
idstringRequiredThe
idof the question.labelstringRequiredThe question as it was asked.
kindstringRequired- One of
"text""long-text""phone""choice""checkbox" valuestringRequiredThe answer. A
checkboxanswersyesorno.
locationstringRequiredWhere the meeting happens, as the guest was told: the link, the phone number or the address.
eventIdstringRequiredThe calendar event of the booking, as
GET /calendar/events/{id}reads it. Null once the booking ended and its event was removed.Can be nullendedBystringRequiredWho declined or cancelled it.
Can be nullOne of"host""guest"endReasonstringRequiredThe reason they gave.
Can be nullrescheduleCountintegerRequiredHow often the meeting was moved.
At least 0guestMailFailedbooleanRequiredTrue when the last email to the guest could not be sent.
POST /bookings/{id}/resendtries again.createdAtstringRequiredWhen the guest booked.
Formatdate-time
BookingAnalyticsobject
objectstringRequired- One of
"booking_analytics" pageIdstringRequiredThe booking page the numbers are for when they are for exactly one, or null.
Can be nullpageIdsstring[]RequiredThe booking pages the numbers are for, or an empty list for every page of the person.
sincestringRequiredThe start of the oldest bucket, where the window begins.
Formatdate-timeuntilstringRequiredNow, where the window ends.
Formatdate-timegrainstringRequired- One of
"minute""hour""day" offsetMinutesintegerRequiredThe offset the buckets were cut in.
totalsobjectRequiredbookedintegerRequiredBookings made in the window, whatever became of them.
At least 0confirmedintegerRequiredOf those, the meetings that stand, held or still to come.
At least 0pendingintegerRequiredOf those, the requests still waiting for an answer.
At least 0expiredintegerRequiredOf those, the requests nobody answered before their time came.
At least 0declinedintegerRequiredOf those, the requests the host turned down.
At least 0cancelledintegerRequiredOf those, the meetings called off.
At least 0cancelledByGuestintegerRequiredCancelled by the guest.
At least 0cancelledByHostintegerRequiredCancelled by the host.
At least 0rescheduledintegerRequiredOf those, the meetings moved at least once.
At least 0minutesBookedintegerRequiredThe minutes of the confirmed meetings.
At least 0cancellationRatenumberRequiredCancelled divided by booked, or null when nothing was booked.
Can be nullAt least 0At most 1
upcomingobjectRequiredThe calendar right now, whatever the window.
confirmedintegerRequiredConfirmed meetings that have not ended.
At least 0waitingintegerRequiredRequests that wait for approval and whose time has not come.
At least 0nextStartstringRequiredWhen the next confirmed meeting starts, or null when none is coming.
Can be nullFormatdate-time
seriesobject[]RequiredBookings made per bucket, oldest first. A bucket with nothing in it has no entry, so a chart must fill the gaps.
bucketisYYYY-MM-DD,YYYY-MM-DDTHHorYYYY-MM-DDTHH:MMbygrain.bucketstringRequiredbookedintegerRequiredBookings made in the bucket.
At least 0cancelledintegerRequiredOf those, the ones called off since.
At least 0
pagesobject[]RequiredThe pages that got bookings in the window, most first, at most 10.
pageIdstringRequirednamestringRequiredbookedintegerRequiredBookings made on the page in the window.
At least 0cancelledintegerRequiredOf those, the ones called off since.
At least 0
weekdaysobject[]RequiredThe meetings booked in the window that stand or wait for approval, by the weekday they fall on, Sunday (0) to Saturday (6), always seven entries.
weekdayintegerRequired- At least 0At most 6
meetingsintegerRequiredMeetings on that weekday.
At least 0
BookingListobject
objectstring- One of
"list" dataBooking[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn 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" idstringRequiredThe id, which starts with
bkp_.slugstringRequiredThe 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 Nextmail.namestringRequiredWhat the page is called, shown to guests as its heading, such as
Intro call.statusstringRequiredactivetakes bookings.pausedkeeps the link working but offers no times.One of"active""paused"urlstringRequiredThe public link to hand to guests.
problemstringRequiredWhat stops the page from taking bookings, or null:
senderwhenconfig.fromEmailcan no longer send,hourswhen no hours are open at all, andhostwhen the person left the workspace.Can be nullOne of"sender""host""hours"configBookingPageConfigRequiredcountsobjectRequiredupcomingintegerRequiredConfirmed bookings that have not started.
At least 0pendingintegerRequiredBookings that wait for approval.
At least 0
awayobject[]RequiredThe out of office periods of
config.fromEmailthat are running or still to come. Whileconfig.busy.outOfOfficeis true the page offers no times inside them.addressstringRequiredThe address, or the catch-all such as
*@example.com, that is out of office.startsAtstringRequiredWhen the period starts.
Formatdate-timeendsAtstringRequiredWhen it ends, or null while it has no end date.
Can be nullFormatdate-time
createdAtstringRequiredWhen the page was created.
Formatdate-timeupdatedAtstringRequiredWhen the page last changed.
Formatdate-time
BookingPageConfigobject
descriptionstringRequiredText shown under the name of the page. Basic Markdown works: bold, italic, links and lists.
Up to 2000 charactershostNamestringRequiredThe name guests see as the person they meet. Defaults to the name of the account.
Up to 80 charactersdurationsinteger[]RequiredThe meeting lengths a guest can pick, in minutes, each a multiple of 5 between 5 and 720.
1 to 4 itemsapprovalbooleanRequiredTrue holds each new booking as a request until it is approved or declined. False confirms it at once.
fromEmailstringRequiredThe 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 charactersnotifyHostbooleanRequiredWhether that address gets an email about each new, moved or cancelled booking.
questionsobject[]RequiredWhat the guest is asked besides their name and email, at most 10.
Up to 10 itemsidstringRequiredA stable key for the answers: 4 to 16 lowercase letters and digits, unique on the page.
name,email,phone,timezoneandstartare taken.Pattern^[a-z0-9]{4,16}$kindstringRequiredtext,long-text,phone,choice(one ofoptions) orcheckbox.One of"text""long-text""phone""choice""checkbox"labelstringRequired- 1 to 120 characters
requiredbooleanRequiredoptionsstring[]RequiredThe answers of a
choicequestion, at least two. Empty for the other kinds.Up to 12 itemsplaceholderstringExample text shown in the empty field of a
text,long-textorphonequestion, such asAnything we should know before the meeting?. Up to 160 characters, empty for none. Achoiceorcheckboxquestion ignores it.Up to 160 characters
confirmationstringRequiredText shown to the guest after booking, and added to the confirmation email.
Up to 1000 charactersredirectUrlstringRequiredAn
https://page to send the guest to after booking, or empty.Up to 2000 charactersextraGuestsintegerHow 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 10Default0remindersobjectWhen the guest is emailed a reminder and when the host is reminded, each a list of minutes before the start.
Default{"guest":[1440],"host":[10]}guestinteger[]RequiredMinutes before the start to email the guest a reminder, at most 3, each one of 10, 30, 60, 120, 1440, 2880, 10080. Defaults to one day before. An empty list sends none.
Up to 3 itemshostinteger[]RequiredMinutes before the start the host is reminded by the alarm on the meeting in their calendar, at most 3, each one of 0, 5, 10, 15, 30, 60, 1440. Defaults to 10. It applies to meetings booked after it changes.
Up to 3 items
locationobjectRequiredWhere the meeting happens.
kindstringRequiredvideowith a fixed link invalue,phone(the guest is asked for a number),in-personwith the address invalue, ornone.One of"video""phone""in-person""none"valuestringRequiredThe
https://link of avideomeeting or the address of anin-personone.Up to 500 characters
availabilityobjectRequiredWhen the page offers times, before the calendar is taken out.
timezonestringRequiredThe IANA time zone the hours below are read in.
1 to 64 charactersweeklyobject[][]RequiredSeven lists, Sunday first, of the hours open on that weekday. An empty list closes the day.
7 to 7 itemsstartintegerRequiredMinutes after midnight the range opens, so
540is 09:00.At least 0At most 1440endintegerRequiredMinutes after midnight the range closes, later than
start.At least 0At most 1440
overridesobject[]RequiredDates with their own hours, at most 180.
dateisYYYY-MM-DDin the time zone of the page, and an emptyrangescloses that date.Up to 180 itemsdatestringRequiredrangesobject[]Required- Up to 6 items
startintegerRequiredMinutes after midnight the range opens, so
540is 09:00.At least 0At most 1440endintegerRequiredMinutes after midnight the range closes, later than
start.At least 0At most 1440
rulesobjectRequiredThe limits on which of the open hours are offered.
noticeMinutesintegerRequiredHow many minutes ahead a booking has to be made.
At least 0At most 43200horizonDaysintegerRequiredHow many days ahead the page offers times, up to 365.
At least 1At most 365intervalMinutesintegerRequiredMinutes 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 nullbufferBeforeMinutesintegerRequiredMinutes kept free before every meeting, up to 240.
At least 0At most 240bufferAfterMinutesintegerRequiredMinutes kept free after every meeting, up to 240.
At least 0At most 240dailyLimitintegerRequiredThe most bookings this page takes on one day, up to 50. Null for no limit.
Can be nullAt least 1At most 50
appearanceobjectRequiredHow the public page looks.
accentstringRequiredThe colour of buttons and the picked day, as
#rrggbb.Pattern^#[0-9a-f]{6}$themestringRequiredautofollows the device of the guest, or forcelightordark.One of"auto""light""dark"showAvatarbooleanRequiredbackgroundstringWhat fills the page behind the card:
default, one of the presetsdusk,mist,sand,night,meadow,dots,brush,trail,ember,canvas,bloom,field,wandererandgold,imagefor the uploaded background image, or a colour as#rrggbb. Defaults todefault.Default"default"fontsobjectThe typefaces of the public page:
primaryfor its text andsecondaryfor its title. Each is one of the brand fonts the workspace appearance offers, or null for the standard font.Default{"primary":null,"secondary":null}primarystringThe font of the text, such as
inter. Null uses the standard font.Can be nullOne of"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"DefaultnullsecondarystringThe font of the title, such as
instrument-serif. Null keeps the title in the font of the text.Can be nullOne of"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"Defaultnull
backgroundImagestringThe address of the uploaded background image, or null. Read only: upload one with
PUT /booking-pages/{id}/backgroundand remove it withDELETEon the same path.Can be nullUp to 2000 charactersDefaultnull
guestChangesobjectRequiredWhat a guest may do from the link in their emails.
cancelbooleanRequiredreschedulebooleanRequiredcutoffMinutesintegerRequiredHow many minutes before the meeting those changes close.
At least 0At most 20160
busyobjectRequiredWhat counts as busy besides the events the person made and the bookings they already have.
addressesstring[]RequiredThe addresses whose invitations block time unless declined. Null checks every address the person holds.
Can be nullUp to 50 itemssubscriptionsbooleanRequiredWhether events from calendars the person subscribed to block time.
outOfOfficebooleanWhether the page offers no times while
fromEmailis out of office. Defaults to true.Defaulttrue
seoobjectHow the public page presents itself to browsers and search engines.
Default{}titlestringThe title of the browser tab and of a search result. Empty uses the name of the page and the host.
Up to 120 charactersDefault""descriptionstringThe summary under the title in a search result. Empty uses the start of the description.
Up to 300 charactersDefault""indexablebooleanWhether search engines may list the page. False, the default, asks them not to.
Defaultfalse
BookingPageListobject
objectstring- One of
"list" dataBookingPage[]
BookingTimesobject
objectstringRequired- One of
"booking_times" pageIdstringRequiredtimezonestringRequiredThe time zone of the page.
durationMinutesintegerRequiredThe meeting length the times are for.
timesstring[]RequiredEvery open start time in the window, in order.
DeletedBookingPageobject
objectstringRequired- One of
"booking_page" idstringRequireddeletedbooleanRequired- One of
true
Google Workspace