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"
}| Field | Type | Description |
|---|---|---|
| id | string | Booking page ID (starts with bkp_). |
| mailbox | string | The mailbox whose availability the page exposes. |
| slug | string | URL slug for the public booking page. |
| url | string | null | Public booking link, served under the mailbox's domain. |
| name | string | Display name. |
| description | string | null | Optional description. |
| duration_minutes | integer | Meeting length in minutes. |
| availability_days | integer[] | Weekdays offered, from 0 for Sunday to 6 for Saturday. |
| window_start_minutes | integer | Start of the daily window, minutes from midnight. |
| window_end_minutes | integer | End of the daily window, minutes from midnight. |
| timezone | string | IANA time zone the window is defined in. |
| lock_timezone | boolean | When true, every visitor sees times in timezone, with no zone selector. Defaults to false. |
| buffer_minutes | integer | Padding around existing events. |
| minimum_notice_minutes | integer | Minimum notice before the first slot. |
| max_advance_days | integer | How far ahead visitors can book. |
| conferencing_provider | "zoom" | "google_meet" | null | Opt-in provider used to create a meeting for each booking. |
| active | boolean | Whether the page accepts bookings. |
| created_at | string | ISO 8601 timestamp. |
| updated_at | string | ISO 8601 timestamp. |
List and get
GET /v1/booking-pages
GET /v1/booking-pages/:idScope: booking_pages:read. The list endpoint supports cursor and limit pagination.
Read a page's slots
/v1/booking-pages/:id/slotsscope calendar:readReturns 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
/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/:idScope: 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.