Skip to content

Calendar APIBooking pages

Booking pages API

A booking page shows when one mailbox is free at a public URL, so visitors can pick a slot and book a meeting. Booking pages are the only calendar configuration Shipmail stores. Shipmail works out the slots from the owner's calendar on each request and never stores them. One-off links are not listed here; see the booking links API.

Last updated

The booking page object

{
  "object": "booking_page",
  "id": "bkp_abc123",
  "mailbox": "hello@yourdomain.com",
  "slug": "intro",
  "url": "https://shipmail.to/book/yourdomain.com/intro",
  "name": "Intro call",
  "description": null,
  "duration_minutes": 30,
  "availability_days": [1, 2, 3, 4, 5],
  "window_start_minutes": 540,
  "window_end_minutes": 1020,
  "timezone": "America/New_York",
  "lock_timezone": false,
  "buffer_minutes": 0,
  "minimum_notice_minutes": 0,
  "max_advance_days": 30,
  "conferencing_provider": "zoom",
  "active": true,
  "created_at": "2026-07-07T10:00:00.000Z",
  "updated_at": "2026-07-07T10:00:00.000Z"
}
FieldTypeDescription
idstringBooking page ID (starts with bkp_).
mailboxstringThe mailbox whose availability the page exposes.
slugstringURL slug for the public booking page.
urlstring | nullPublic booking link, served under the mailbox's domain.
namestringDisplay name.
descriptionstring | nullOptional description.
duration_minutesintegerMeeting length in minutes.
availability_daysinteger[]Weekdays offered, from 0 for Sunday to 6 for Saturday.
window_start_minutesintegerStart of the daily window, minutes from midnight.
window_end_minutesintegerEnd of the daily window, minutes from midnight.
timezonestringIANA time zone the window is defined in.
lock_timezonebooleanWhen true, every visitor sees times in timezone, with no zone selector. Defaults to false.
buffer_minutesintegerPadding around existing events.
minimum_notice_minutesintegerMinimum notice before the first slot.
max_advance_daysintegerHow far ahead visitors can book.
conferencing_provider"zoom" | "google_meet" | nullOpt-in provider used to create a meeting for each booking.
activebooleanWhether the page accepts bookings.
created_atstringISO 8601 timestamp.
updated_atstringISO 8601 timestamp.

List and get

GET /v1/booking-pages
GET /v1/booking-pages/:id

Scope: booking_pages:read. The list endpoint supports cursor and limit pagination.

Read a page's slots

GET/v1/booking-pages/:id/slotsscope calendar:read

Returns the open slots the page offers, computed exactly as its public page computes them, as UTC instants. from defaults to now and to to the end of the page's booking horizon. The window can span at most 62 days, and a window holding 5,000 slots or more is refused with a 422. A page that is not active offers no slots. timezone is the page's zone, for showing the times.

GET /v1/booking-pages/bkp_abc123/slots?from=2026-11-09T00:00:00Z&to=2026-11-16T00:00:00Z
{
  "object": "booking_page_slots",
  "booking_page_id": "bkp_abc123",
  "timezone": "America/New_York",
  "duration_minutes": 30,
  "from": "2026-11-09T00:00:00.000Z",
  "to": "2026-11-16T00:00:00.000Z",
  "slots": [
    { "start": "2026-11-09T14:00:00.000Z", "end": "2026-11-09T14:30:00.000Z" },
    { "start": "2026-11-09T14:30:00.000Z", "end": "2026-11-09T15:00:00.000Z" }
  ]
}

GET /v1/calendar/availability does not read a booking page and defaults to Etc/UTC, so use this endpoint to know which times a page shows.

Create a booking page

POST/v1/booking-pagesscope booking_pages:write
{
  "name": "Intro call",
  "mailbox": "hello@yourdomain.com",
  "slug": "intro",
  "duration_minutes": 30,
  "availability_days": [1, 2, 3, 4, 5],
  "window_start_minutes": 540,
  "window_end_minutes": 1020,
  "timezone": "America/New_York",
  "conferencing_provider": "zoom"
}

Conferencing is opt-in per booking page. The selected provider must already be connected to the page's mailbox, or the request is rejected. See Zoom and Google Meet.

Update or delete

PATCH  /v1/booking-pages/:id
DELETE /v1/booking-pages/:id

Scope: booking_pages:write. PATCH accepts any subset of the create fields. DELETE returns 204.

{
  "conferencing_provider": null
}

Set conferencing_provider to null to stop creating meeting links.