--- title: "nextmail bookings" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://nextmail.sh/docs/cli/reference/bookings" area: "CLI" category: "Reference" --- # nextmail bookings Every command in this namespace, with its arguments, flags and examples. ## Commands ### `nextmail bookings list-pages` List the booking pages of the person ```bash nextmail bookings list-pages [flags] ``` Resolves the booking pages of the person, oldest first unless `sort` says otherwise. `q` searches the name and the link, `status` keeps the active or the paused pages, and `since` and `until` keep the pages made in a window. A booking page is a public link, `/book/`, where somebody picks a free time and books a meeting on the calendar of that person. Each page comes with its settings in `config`, the link to hand to guests in `url`, and in `counts` how many of its bookings are upcoming and how many wait for approval. `status` is `active` while the page takes bookings and `paused` while its link works but offers no times. `problem` says what stops a page from taking bookings and is null when nothing does. `away` lists the out of office periods that close the page. A person holds at most 25 pages, so the list comes whole and is never paged. - Scopes: `calendar:read`. - Needs a sign-in. **Flags** - `--q `: Only the pages whose name or link contains this text, at most 200 characters. Case and accents are ignored. - `--status `: `active` for the pages that take bookings, `paused` for the ones that do not. Left out, both. - `--since `: Only the pages made at or after this instant, as a `Date` or an ISO 8601 string. - `--until `: Only the pages made before this instant, later than `since`. - `--sort `: `oldest` (the default) or `newest` by when the page was made, `name` from A to Z, or `upcoming` with the most upcoming meetings first. **Examples** ```bash nextmail bookings list-pages ``` Print the raw JSON ```bash nextmail bookings list-pages --json ``` Also available in: API [`GET /booking-pages`](https://nextmail.sh/docs/api/reference/booking-pages#get-booking-pages); TypeScript [`nextmail.bookings.listPages()`](https://nextmail.sh/docs/sdk/reference/bookings#listPages); Python [`bookings.list_pages()`](https://nextmail.sh/docs/python/reference/bookings#listPages); Ruby [`bookings.list_pages`](https://nextmail.sh/docs/ruby/reference/bookings#listPages); PHP [`bookings->listPages`](https://nextmail.sh/docs/php/reference/bookings#listPages); Go [`Bookings.ListPages`](https://nextmail.sh/docs/go/reference/bookings#listPages); Java [`bookings().listPages`](https://nextmail.sh/docs/java/reference/bookings#listPages); C# [`Bookings.ListPagesAsync`](https://nextmail.sh/docs/csharp/reference/bookings#listPages). ### `nextmail bookings get-page` Read one booking page by id ```bash nextmail bookings get-page [flags] ``` Looks up a single booking page and returns it in the same shape as a row of `listPages`, with every setting in `config`: the meeting lengths, where the meeting happens, the weekly hours and the dates with their own hours, the notice, the buffers and the daily limit, whether a booking waits for approval, the address its emails come from, the questions a guest is asked, how the page looks and what a guest may change afterwards. `config.availability.weekly` holds seven lists, Sunday first, of the hours open on that weekday, each as minutes after midnight in `config.availability.timezone`. `problem` says what stops the page from taking bookings, and `away` lists 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. - Scopes: `calendar:read`. - Needs a sign-in. **Arguments** - `` (required): Booking page id such as `bkp_5c1e9a7b3d2f48e6a0b4c7d1`, as `listPages` returns it. **Examples** ```bash nextmail bookings get-page bkp_5c1e9a7b3d2f48e6a0b4c7d1 ``` Print the raw JSON ```bash nextmail bookings get-page bkp_5c1e9a7b3d2f48e6a0b4c7d1 --json ``` Also available in: API [`GET /booking-pages/{id}`](https://nextmail.sh/docs/api/reference/booking-pages#get-booking-pages-id); TypeScript [`nextmail.bookings.getPage()`](https://nextmail.sh/docs/sdk/reference/bookings#getPage); Python [`bookings.get_page()`](https://nextmail.sh/docs/python/reference/bookings#getPage); Ruby [`bookings.get_page`](https://nextmail.sh/docs/ruby/reference/bookings#getPage); PHP [`bookings->getPage`](https://nextmail.sh/docs/php/reference/bookings#getPage); Go [`Bookings.GetPage`](https://nextmail.sh/docs/go/reference/bookings#getPage); Java [`bookings().getPage`](https://nextmail.sh/docs/java/reference/bookings#getPage); C# [`Bookings.GetPageAsync`](https://nextmail.sh/docs/csharp/reference/bookings#getPage). ### `nextmail bookings create-page` Create a booking page ```bash nextmail bookings create-page --name [flags] nextmail bookings create-page --data [flags] ``` Creates a booking page and resolves with it as it is stored. The page takes bookings at once, at the link in `url`. Only `name` is required: the page starts with weekdays from 09:00 to 17:00, 30 minute meetings, four hours of notice, times up to 60 days ahead and the first address the person may send from. Anything in `config` replaces that default, and what it leaves out keeps it. `slug` is the last part of the public link, `/book/`. Left out, it is made from the name. `timezone` says which time zone the working hours are read in when `config.availability.timezone` is not sent. The times a page offers are its working hours 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 organised by `config.fromEmail`, and the guest is told by email from that address, so the call needs `emails:send` beside `calendar:write`. - Scopes: `calendar:write`, `emails:send`. - Needs a sign-in. **Flags** - `--name `: What the page is called, shown to guests as its heading, such as `Intro call`. Trimmed, 1 to 80 characters. Required, here or in `--data`. - `--slug `: The last part of the public link: 3 to 60 lowercase letters and digits, with single hyphens between words. It is unique across Nextmail. Left out, it is made from the name. - `--timezone `: The IANA time zone the working hours are read in, such as `Europe/Berlin`, when `config.availability.timezone` is not sent. Defaults to `UTC`. - `--config-description `: Text shown under the name of the page, up to 2,000 characters. Basic Markdown works: bold, italic, links and lists. Defaults to none. - `--config-host-name `: The name guests see as the person they meet, up to 80 characters. Defaults to the name of the account. - `--config-durations ` (repeatable): The meeting lengths a guest can pick, in minutes: 1 to 4 of them, each a multiple of 5 between 5 and 720. Defaults to `[30]`. - `--config-location-kind `: Where the meeting happens: `video` with a fixed link in `value`, `phone`, where the guest is asked for a number, `in-person` with the address in `value`, or `none`. Defaults to `none`. - `--config-location-value `: The `https://` link of a `video` meeting or the address of an `in-person` one, up to 500 characters. It is dropped for `phone` and `none`. - `--config-availability-timezone `: The IANA time zone the hours of the page are read in. Defaults to `timezone`. - `--config-availability-weekly `: Seven lists, Sunday first, of the hours open on that weekday. Each range is `{ start, end }` in minutes after midnight, so `{ start: 540, end: 1020 }` is 09:00 to 17:00. An empty list closes the day, and a day takes at most 6 ranges. Defaults to 09:00 to 17:00 from Monday to Friday. JSON shaped as `Array>`, inline or from a file with @path. - `--config-availability-overrides `: Dates with their own hours, at most 180, each `{ date, ranges }`. `date` is `YYYY-MM-DD` in the time zone of the page, and an empty `ranges` closes that date. Defaults to none. JSON shaped as `Array`, inline or from a file with @path. - `--config-rules-notice-minutes `: How many minutes ahead a booking has to be made, from 0 to 43,200. Defaults to 240. - `--config-rules-horizon-days `: How many days ahead the page offers times, from 1 to 365. Defaults to 60. - `--config-rules-interval-minutes `: Minutes between two start times: 5, 10, 15, 20, 30, 45, 60, 90 or 120. Null, the default, steps by the length of the meeting. - `--config-rules-buffer-before-minutes `: Minutes kept free before every meeting, from 0 to 240. Defaults to 0. - `--config-rules-buffer-after-minutes `: Minutes kept free after every meeting, from 0 to 240. Defaults to 0. - `--config-rules-daily-limit `: The most bookings the page takes on one day, from 1 to 50. Null, the default, sets no limit. - `--config-approval`: True holds each new booking as a request until `approve` or `decline` answers it. False, the default, confirms it at once. - `--config-from-email `: 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. Defaults to the first such address. - `--config-notify-host`: Whether `fromEmail` gets an email about each new, moved or cancelled booking. Defaults to true. - `--config-questions `: What the guest is asked besides their name and email, at most 10, each `{ id, kind, label, required, options, placeholder }`. `id` is a stable key for the answers: 4 to 16 lowercase letters and digits, unique on the page. `kind` is `text`, `long-text`, `phone`, `choice` or `checkbox`. `options` holds the answers of a `choice` question, from 2 to 12, and is empty for the other kinds. `placeholder` is optional example text shown in the empty field of a `text`, `long-text` or `phone` question, up to 160 characters. Defaults to none. JSON shaped as `Array`, inline or from a file with @path. - `--config-confirmation `: Text shown to the guest after booking and added to the confirmation email, up to 1,000 characters. Defaults to none. - `--config-redirect-url `: An `https://` page to send the guest to after booking, or an empty string for none, which is the default. - `--config-appearance-accent `: The colour of buttons and the picked day, as `#rrggbb`. Defaults to `#18181b`. - `--config-appearance-theme `: `auto` follows the device of the guest, and `light` or `dark` forces one. Defaults to `auto`. - `--config-appearance-show-avatar`: Whether the page shows the photo of the person, or their initials when they have none. Defaults to true. - `--config-appearance-background `: What fills the page behind the card: `default`, one of the presets `dusk`, `mist`, `sand`, `night`, `meadow`, `dots`, `brush`, `trail`, `ember`, `canvas`, `bloom`, `field`, `wanderer` and `gold`, or a colour as `#rrggbb`. Defaults to `default`. `image` shows the photo uploaded with `uploadBackground`, so a new page cannot start with it: that answers 422 `invalid_booking_page`. - `--config-appearance-fonts-primary `: The font of the text: one of the ids in `BRAND_FONT_IDS`, such as `inter` or `georgia`, or null for the default. Defaults to null. - `--config-appearance-fonts-secondary `: The font of the title, such as `instrument-serif`, or null to keep the title in the font of the text. Defaults to null. - `--config-guest-changes-cancel`: Whether a guest may cancel from the link in their emails. Defaults to true. - `--config-guest-changes-reschedule`: Whether a guest may move the meeting from the link in their emails. Defaults to true. - `--config-guest-changes-cutoff-minutes `: How many minutes before the meeting those changes close, from 0 to 20,160. Defaults to 0. - `--config-busy-addresses ` (repeatable): The addresses whose invitations block time unless declined, at most 50. Null, the default, checks every address the person holds. - `--config-busy-subscriptions`: Whether events from calendars the person subscribed to block time. Defaults to true. - `--config-busy-out-of-office`: Whether the page offers no times while `fromEmail` is out of office. Defaults to true. - `--config-seo-title `: The title of the browser tab and of a search result, up to 120 characters. Empty, the default, uses the name of the page and the host. - `--config-seo-description `: The summary under the title in a search result, up to 300 characters. Empty, the default, uses the start of the description. - `--config-seo-indexable`: Whether search engines may list the page. Defaults to false, which asks them not to. - `--config-extra-guests `: 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. - `--config-reminders-guest ` (repeatable): When the guest gets a reminder email, in minutes before the meeting: up to three of 10, 30, 60, 120, 1440, 2880 and 10080. Defaults to one day before, and an empty list sends none. - `--config-reminders-host ` (repeatable): The reminders each booked meeting carries on your own calendar, in minutes before it: up to three of 0, 5, 10, 15, 30, 60 and 1440. Defaults to 10. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash nextmail bookings create-page --name 'Intro call' ``` With optional flags ```bash nextmail bookings create-page --name 'Intro call' --timezone Europe/Berlin --config-description 'A first conversation about your project.' --config-durations 30,60 ``` Read the whole body from a JSON file ```bash nextmail bookings create-page --data @booking.json ``` Also available in: API [`POST /booking-pages`](https://nextmail.sh/docs/api/reference/booking-pages#post-booking-pages); TypeScript [`nextmail.bookings.createPage()`](https://nextmail.sh/docs/sdk/reference/bookings#createPage); Python [`bookings.create_page()`](https://nextmail.sh/docs/python/reference/bookings#createPage); Ruby [`bookings.create_page`](https://nextmail.sh/docs/ruby/reference/bookings#createPage); PHP [`bookings->createPage`](https://nextmail.sh/docs/php/reference/bookings#createPage); Go [`Bookings.CreatePage`](https://nextmail.sh/docs/go/reference/bookings#createPage); Java [`bookings().createPage`](https://nextmail.sh/docs/java/reference/bookings#createPage); C# [`Bookings.CreatePageAsync`](https://nextmail.sh/docs/csharp/reference/bookings#createPage). ### `nextmail bookings update-page` Change the name, the link, the status or any setting of a booking page ```bash nextmail bookings update-page [flags] ``` Changes a booking page and resolves with it as it is stored. Send only what changes: a field left out stays as it is, and a patch with nothing in it is a 422. `config` is merged, not replaced. A top-level value such as `approval` or `fromEmail` replaces the stored one. Inside `location`, `availability`, `rules`, `appearance`, `guestChanges`, `busy`, `seo` and `reminders` each field is merged on its own, and so is each font in `appearance.fonts`, so `rules: { dailyLimit: 4 }` leaves the notice and the buffers alone. A list is replaced whole: send every entry of `durations`, `questions`, `availability.weekly` or `availability.overrides` again, not only the ones that change. Set `status` to `paused` to stop offering times without losing the link, and to `active` to offer them again. Bookings already made keep their time whatever changes. A new `slug` moves the page to a new link and the old one stops working, so links already handed out break. - Scopes: `calendar:write`, `emails:send`. - Needs a sign-in. **Arguments** - `` (required): Booking page id such as `bkp_5c1e9a7b3d2f48e6a0b4c7d1`, as `listPages` returns it. **Flags** - `--name `: New name, shown to guests as the heading of the page. Trimmed, 1 to 80 characters. Left out, the name stays. - `--slug `: New last part of the public link: 3 to 60 lowercase letters and digits, with single hyphens between words. It is unique across Nextmail. Left out, the link stays. - `--status `: `active` takes bookings. `paused` keeps the link working but offers no times. Left out, it stays. - `--config-description `: Text shown under the name of the page, up to 2,000 characters. Basic Markdown works: bold, italic, links and lists. An empty string clears it. - `--config-host-name `: The name guests see as the person they meet, up to 80 characters. - `--config-durations ` (repeatable): The meeting lengths a guest can pick, in minutes, replacing the list the page had: 1 to 4 of them, each a multiple of 5 between 5 and 720. - `--config-location-kind `: Where the meeting happens: `video` with a fixed link in `value`, `phone`, where the guest is asked for a number, `in-person` with the address in `value`, or `none`. - `--config-location-value `: The `https://` link of a `video` meeting or the address of an `in-person` one, up to 500 characters. It is dropped for `phone` and `none`. - `--config-availability-timezone `: The IANA time zone the hours of the page are read in, such as `Europe/Berlin`. - `--config-availability-weekly `: All seven lists again, Sunday first, of the hours open on that weekday. Each range is `{ start, end }` in minutes after midnight, so `{ start: 540, end: 1020 }` is 09:00 to 17:00. An empty list closes the day, and a day takes at most 6 ranges. JSON shaped as `Array>`, inline or from a file with @path. - `--config-availability-overrides `: Every date with its own hours again, at most 180, each `{ date, ranges }`. `date` is `YYYY-MM-DD` in the time zone of the page, and an empty `ranges` closes that date. An empty array removes them all. JSON shaped as `Array`, inline or from a file with @path. - `--config-rules-notice-minutes `: How many minutes ahead a booking has to be made, from 0 to 43,200. - `--config-rules-horizon-days `: How many days ahead the page offers times, from 1 to 365. - `--config-rules-interval-minutes `: Minutes between two start times: 5, 10, 15, 20, 30, 45, 60, 90 or 120. Null steps by the length of the meeting. - `--config-rules-buffer-before-minutes `: Minutes kept free before every meeting, from 0 to 240. - `--config-rules-buffer-after-minutes `: Minutes kept free after every meeting, from 0 to 240. - `--config-rules-daily-limit `: The most bookings the page takes on one day, from 1 to 50. Null sets no limit. - `--config-approval`: True holds each new booking as a request until `approve` or `decline` answers it. False confirms it at once. Requests already waiting keep waiting. - `--config-from-email `: 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. - `--config-notify-host`: Whether `fromEmail` gets an email about each new, moved or cancelled booking. - `--config-questions `: Every question again, at most 10, each `{ id, kind, label, required, options, placeholder }`. `id` is a stable key for the answers: 4 to 16 lowercase letters and digits, unique on the page. `kind` is `text`, `long-text`, `phone`, `choice` or `checkbox`. `options` holds the answers of a `choice` question, from 2 to 12, and is empty for the other kinds. `placeholder` is optional example text shown in the empty field of a `text`, `long-text` or `phone` question, up to 160 characters. An empty array asks nothing more. JSON shaped as `Array`, inline or from a file with @path. - `--config-confirmation `: Text shown to the guest after booking and added to the confirmation email, up to 1,000 characters. An empty string clears it. - `--config-redirect-url `: An `https://` page to send the guest to after booking, or an empty string for none. - `--config-appearance-accent `: The colour of buttons and the picked day, as `#rrggbb`. - `--config-appearance-theme `: `auto` follows the device of the guest, and `light` or `dark` forces one. - `--config-appearance-show-avatar`: Whether the page shows the photo of the person, or their initials when they have none. - `--config-appearance-background `: What fills the page behind the card: `default`, one of the presets `dusk`, `mist`, `sand`, `night`, `meadow`, `dots`, `brush`, `trail`, `ember`, `canvas`, `bloom`, `field`, `wanderer` and `gold`, a colour as `#rrggbb`, or `image` for the photo uploaded with `uploadBackground`. `image` without an uploaded photo is a 422 `invalid_booking_page`. - `--config-appearance-fonts-primary `: The font of the text: one of the ids in `BRAND_FONT_IDS`, such as `inter` or `georgia`, or null for the default. Left out, it keeps its value. - `--config-appearance-fonts-secondary `: The font of the title, such as `instrument-serif`, or null to keep the title in the font of the text. Left out, it keeps its value. - `--config-guest-changes-cancel`: Whether a guest may cancel from the link in their emails. - `--config-guest-changes-reschedule`: Whether a guest may move the meeting from the link in their emails. - `--config-guest-changes-cutoff-minutes `: How many minutes before the meeting those changes close, from 0 to 20,160. - `--config-busy-addresses ` (repeatable): The addresses whose invitations block time unless declined, at most 50. Null checks every address the person holds. - `--config-busy-subscriptions`: Whether events from calendars the person subscribed to block time. - `--config-busy-out-of-office`: Whether the page offers no times while `fromEmail` is out of office. - `--config-seo-title `: The title of the browser tab and of a search result, up to 120 characters. An empty string goes back to the name of the page and the host. - `--config-seo-description `: The summary under the title in a search result, up to 300 characters. An empty string goes back to the start of the description. - `--config-seo-indexable`: Whether search engines may list the page. - `--config-extra-guests `: How many other people a guest may add to a booking, 0 to 10. Each one gets the invitation and every later change. 0 hides the field. - `--config-reminders-guest ` (repeatable): When the guest gets a reminder email, in minutes before the meeting: up to three of 10, 30, 60, 120, 1440, 2880 and 10080. An empty list sends none. - `--config-reminders-host ` (repeatable): The reminders each new booking carries on your own calendar, in minutes before it: up to three of 0, 5, 10, 15, 30, 60 and 1440. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** With optional flags ```bash nextmail bookings update-page bkp_5c1e9a7b3d2f48e6a0b4c7d1 --config-durations 45 --config-rules-buffer-after-minutes 15 --config-rules-daily-limit 4 ``` Print the raw JSON ```bash nextmail bookings update-page bkp_5c1e9a7b3d2f48e6a0b4c7d1 --config-durations 45 --config-rules-buffer-after-minutes 15 --config-rules-daily-limit 4 --json ``` Also available in: API [`PATCH /booking-pages/{id}`](https://nextmail.sh/docs/api/reference/booking-pages#patch-booking-pages-id); TypeScript [`nextmail.bookings.updatePage()`](https://nextmail.sh/docs/sdk/reference/bookings#updatePage); Python [`bookings.update_page()`](https://nextmail.sh/docs/python/reference/bookings#updatePage); Ruby [`bookings.update_page`](https://nextmail.sh/docs/ruby/reference/bookings#updatePage); PHP [`bookings->updatePage`](https://nextmail.sh/docs/php/reference/bookings#updatePage); Go [`Bookings.UpdatePage`](https://nextmail.sh/docs/go/reference/bookings#updatePage); Java [`bookings().updatePage`](https://nextmail.sh/docs/java/reference/bookings#updatePage); C# [`Bookings.UpdatePageAsync`](https://nextmail.sh/docs/csharp/reference/bookings#updatePage). ### `nextmail bookings upload-background` Upload the background photo of a booking page ```bash nextmail bookings upload-background [flags] ``` Sends the image bytes as the request body, replacing the photo there was, and resolves with the page. The photo fills the public page behind the card: `config.appearance.background` becomes `image` and `config.appearance.backgroundImage` holds the address of the stored photo. Up to 5 MB goes in, and it is fitted into 2560 by 1600 pixels and stored as WebP. It takes PNG, JPEG, WebP or GIF, and an animated image keeps its first frame. The type is read from `--content-type`, or from a `Blob`'s own type when that is left out, and without either the server refuses the bytes with 422 `invalid_image`. To go back to a preset or a colour and keep the photo for later, set `config.appearance.background` with `updatePage`. `removeBackground` deletes the photo. - Scopes: `calendar:write`, `emails:send`. - Needs a sign-in. **Arguments** - `` (required): Booking page id such as `bkp_5c1e9a7b3d2f48e6a0b4c7d1`, as `listPages` returns it. - `` (required): The image: a `Blob`, `ArrayBuffer` or `Uint8Array`. **Flags** - `--content-type `: `image/png`, `image/jpeg`, `image/webp` or `image/gif`. Required unless `data` is a `Blob` with a type. **Examples** The required values only ```bash nextmail bookings upload-background bkp_5c1e9a7b3d2f48e6a0b4c7d1 ./photo.jpg ``` With optional flags ```bash nextmail bookings upload-background bkp_5c1e9a7b3d2f48e6a0b4c7d1 ./photo.jpg --content-type image/jpeg ``` Also available in: API [`PUT /booking-pages/{id}/background`](https://nextmail.sh/docs/api/reference/booking-pages#put-booking-pages-id-background); TypeScript [`nextmail.bookings.uploadBackground()`](https://nextmail.sh/docs/sdk/reference/bookings#uploadBackground); Python [`bookings.upload_background()`](https://nextmail.sh/docs/python/reference/bookings#uploadBackground); Ruby [`bookings.upload_background`](https://nextmail.sh/docs/ruby/reference/bookings#uploadBackground); PHP [`bookings->uploadBackground`](https://nextmail.sh/docs/php/reference/bookings#uploadBackground); Go [`Bookings.UploadBackground`](https://nextmail.sh/docs/go/reference/bookings#uploadBackground); Java [`bookings().uploadBackground`](https://nextmail.sh/docs/java/reference/bookings#uploadBackground); C# [`Bookings.UploadBackgroundAsync`](https://nextmail.sh/docs/csharp/reference/bookings#uploadBackground). ### `nextmail bookings remove-background` Remove the background photo of a booking page ```bash nextmail bookings remove-background [flags] ``` Deletes the stored background photo of a booking page and resolves with the page. A page that showed the photo goes back to the `default` background, and one that showed a preset or a colour keeps it. Removing a photo that is not set changes nothing. - Scopes: `calendar:write`, `emails:send`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Booking page id such as `bkp_5c1e9a7b3d2f48e6a0b4c7d1`, as `listPages` returns it. **Examples** ```bash nextmail bookings remove-background bkp_5c1e9a7b3d2f48e6a0b4c7d1 ``` Skip the confirmation, for scripts ```bash nextmail bookings remove-background bkp_5c1e9a7b3d2f48e6a0b4c7d1 --yes ``` Also available in: API [`DELETE /booking-pages/{id}/background`](https://nextmail.sh/docs/api/reference/booking-pages#delete-booking-pages-id-background); TypeScript [`nextmail.bookings.removeBackground()`](https://nextmail.sh/docs/sdk/reference/bookings#removeBackground); Python [`bookings.remove_background()`](https://nextmail.sh/docs/python/reference/bookings#removeBackground); Ruby [`bookings.remove_background`](https://nextmail.sh/docs/ruby/reference/bookings#removeBackground); PHP [`bookings->removeBackground`](https://nextmail.sh/docs/php/reference/bookings#removeBackground); Go [`Bookings.RemoveBackground`](https://nextmail.sh/docs/go/reference/bookings#removeBackground); Java [`bookings().removeBackground`](https://nextmail.sh/docs/java/reference/bookings#removeBackground); C# [`Bookings.RemoveBackgroundAsync`](https://nextmail.sh/docs/csharp/reference/bookings#removeBackground). ### `nextmail bookings delete-page` Delete a booking page ```bash nextmail bookings delete-page [flags] ``` Deletes a booking page for good. Its public link stops working and the list of its bookings goes with it, so `list` no longer shows them and guests can no longer move or cancel through the links in their emails. The meetings already booked stay on the calendar, where `calendar.cancelEvent` can still call one off. There is no undo. To stop offering times and keep the page, its link and its bookings, use `updatePage` with `status` `paused`. - Scopes: `calendar:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Booking page id such as `bkp_5c1e9a7b3d2f48e6a0b4c7d1`, as `listPages` returns it. **Examples** ```bash nextmail bookings delete-page bkp_5c1e9a7b3d2f48e6a0b4c7d1 ``` Skip the confirmation, for scripts ```bash nextmail bookings delete-page bkp_5c1e9a7b3d2f48e6a0b4c7d1 --yes ``` Also available in: API [`DELETE /booking-pages/{id}`](https://nextmail.sh/docs/api/reference/booking-pages#delete-booking-pages-id); TypeScript [`nextmail.bookings.deletePage()`](https://nextmail.sh/docs/sdk/reference/bookings#deletePage); Python [`bookings.delete_page()`](https://nextmail.sh/docs/python/reference/bookings#deletePage); Ruby [`bookings.delete_page`](https://nextmail.sh/docs/ruby/reference/bookings#deletePage); PHP [`bookings->deletePage`](https://nextmail.sh/docs/php/reference/bookings#deletePage); Go [`Bookings.DeletePage`](https://nextmail.sh/docs/go/reference/bookings#deletePage); Java [`bookings().deletePage`](https://nextmail.sh/docs/java/reference/bookings#deletePage); C# [`Bookings.DeletePageAsync`](https://nextmail.sh/docs/csharp/reference/bookings#deletePage). ### `nextmail bookings list-times` List the times a booking page offers ```bash nextmail bookings list-times [flags] ``` Resolves the start times a guest could book on a page inside a window, in order. They are the 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, its daily limit, its notice and the out of office periods that close it. The window starts at `from`, or now, and ends at `to`, or 14 days later. It covers at most 62 days, and a later `to` is cut back to that. `--duration-minutes` picks which meeting length the times are for and has to be one of the `durations` of the page. Left out, the shortest is used. Both bounds take a `Date` or an ISO 8601 string, and the SDK converts a `Date` with `toISOString()`. With `--booking-id` the times are the ones that booking can move to with `reschedule`: its own time counts as free, and they are for its length. A paused page still answers, so the times can be checked before it is turned on. A page with a `problem` offers nothing. - Scopes: `calendar:read`. - Needs a sign-in. **Arguments** - `` (required): Booking page id such as `bkp_5c1e9a7b3d2f48e6a0b4c7d1`, as `listPages` returns it. **Flags** - `--from `: The start of the window. Defaults to now. - `--to `: The end of the window, later than `from`. Defaults to 14 days after `from`, and counts for at most 62 days after it. - `--duration-minutes `: The meeting length in minutes, one of the `durations` of the page. Defaults to the shortest. - `--booking-id `: A 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, so `--duration-minutes` is ignored. **Examples** The required values only ```bash nextmail bookings list-times bkp_5c1e9a7b3d2f48e6a0b4c7d1 ``` With optional flags ```bash nextmail bookings list-times bkp_5c1e9a7b3d2f48e6a0b4c7d1 --duration-minutes 30 ``` Print the raw JSON ```bash nextmail bookings list-times bkp_5c1e9a7b3d2f48e6a0b4c7d1 --json ``` Also available in: API [`GET /booking-pages/{id}/times`](https://nextmail.sh/docs/api/reference/booking-pages#get-booking-pages-id-times); TypeScript [`nextmail.bookings.listTimes()`](https://nextmail.sh/docs/sdk/reference/bookings#listTimes); Python [`bookings.list_times()`](https://nextmail.sh/docs/python/reference/bookings#listTimes); Ruby [`bookings.list_times`](https://nextmail.sh/docs/ruby/reference/bookings#listTimes); PHP [`bookings->listTimes`](https://nextmail.sh/docs/php/reference/bookings#listTimes); Go [`Bookings.ListTimes`](https://nextmail.sh/docs/go/reference/bookings#listTimes); Java [`bookings().listTimes`](https://nextmail.sh/docs/java/reference/bookings#listTimes); C# [`Bookings.ListTimesAsync`](https://nextmail.sh/docs/csharp/reference/bookings#listTimes). ### `nextmail bookings list` List the meetings guests booked, a page at a time ```bash nextmail bookings list [flags] ``` Resolves one page of bookings: the meetings guests booked on the booking pages of the person, or on some of them with `--page-ids`. `q` searches the guest and the page, and `from` and `to` keep the meetings that start in a window. A booking is a calendar event with the guest invited, so it shows wherever the calendar does, and a meeting moved or cancelled in the calendar reads as moved or cancelled here. `view` picks which bookings are listed. `upcoming`, the default, holds the confirmed meetings that are not over. `pending` holds the requests that wait for `approve` or `decline`, on a page whose `config.approval` is true. `past` holds the meetings that are over and the requests nobody answered in time, and `ended` holds the ones that were declined or cancelled. `upcoming` and `pending` come soonest first, `past` and `ended` latest first. Each booking names its page in `--page-id` and `pageName`, the guest in `guest`, what they answered in `answers` and its calendar event in `eventId`. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `calendar:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--view `: Which bookings to list: `upcoming`, `pending`, `past` or `ended`. Defaults to `upcoming`. - `--page-id `: Only the bookings of this booking page, by its id. Left out, the bookings of every page of the person are listed. - `--page-ids ` (repeatable): Only the bookings of these booking pages, at most 25 ids. Left out, every page of the person. - `--q `: Only the bookings whose guest name, guest email or page name contains this text, at most 200 characters. Case and accents are ignored. - `--from `: Only the meetings that start at or after this instant, as a `Date` or an ISO 8601 string. - `--to `: Only the meetings that start before this instant, later than `from`. - `--limit `: Page size, from 1 to 100. The server defaults to 30. - `--cursor `: The `nextCursor` of the previous page, passed back as it came. Leave it out for the first page. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash nextmail bookings list ``` With optional flags ```bash nextmail bookings list --view pending ``` Walk every page and stop after 100 items ```bash nextmail bookings list --all --max 100 ``` One JSON object per line when piped ```bash nextmail bookings list --all > bookings.ndjson ``` Also available in: API [`GET /bookings`](https://nextmail.sh/docs/api/reference/booking-pages#get-bookings); TypeScript [`nextmail.bookings.list()`](https://nextmail.sh/docs/sdk/reference/bookings#list); Python [`bookings.list()`](https://nextmail.sh/docs/python/reference/bookings#list); Ruby [`bookings.list`](https://nextmail.sh/docs/ruby/reference/bookings#list); PHP [`bookings->list`](https://nextmail.sh/docs/php/reference/bookings#list); Go [`Bookings.List`](https://nextmail.sh/docs/go/reference/bookings#list); Java [`bookings().list`](https://nextmail.sh/docs/java/reference/bookings#list); C# [`Bookings.ListAsync`](https://nextmail.sh/docs/csharp/reference/bookings#list). ### `nextmail bookings get` Read one booking by id ```bash nextmail bookings get [flags] ``` Looks up a single booking and returns it in the same shape as a row of `list`: the booking page it was made on, the guest with the time zone they booked in, what they answered to the questions of the page, where the meeting happens as the guest was told, the calendar event it is and how it ended if it did. A booking follows its calendar event. Reading one first catches up with the calendar, so a meeting that was moved there shows its new `start` and `end`, and one that was cancelled or deleted there reads `cancelled`, or `declined` when it still waited for approval. `endedBy` says whether the `host` or the `guest` declined or cancelled it, and `endReason` holds the reason they gave. `guestMailFailed` is true when the last email to the guest could not be sent, and `resendEmail` tries again. - Scopes: `calendar:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): Booking id such as `bkg_2b8d4f6a1c3e5079b6d8f0a2`, as `list` returns it. **Examples** ```bash nextmail bookings get bkg_2b8d4f6a1c3e5079b6d8f0a2 ``` Print the raw JSON ```bash nextmail bookings get bkg_2b8d4f6a1c3e5079b6d8f0a2 --json ``` Also available in: API [`GET /bookings/{id}`](https://nextmail.sh/docs/api/reference/booking-pages#get-bookings-id); TypeScript [`nextmail.bookings.get()`](https://nextmail.sh/docs/sdk/reference/bookings#get); Python [`bookings.get()`](https://nextmail.sh/docs/python/reference/bookings#get); Ruby [`bookings.get`](https://nextmail.sh/docs/ruby/reference/bookings#get); PHP [`bookings->get`](https://nextmail.sh/docs/php/reference/bookings#get); Go [`Bookings.Get`](https://nextmail.sh/docs/go/reference/bookings#get); Java [`bookings().get`](https://nextmail.sh/docs/java/reference/bookings#get); C# [`Bookings.GetAsync`](https://nextmail.sh/docs/csharp/reference/bookings#get). ### `nextmail bookings approve` Confirm a booking that waits for approval ```bash nextmail bookings approve [flags] ``` Confirms a booking that waits for approval, on a booking page whose `config.approval` is true. The hold on the calendar becomes a confirmed meeting, and the guest is told by email, sent from the address of the page with the calendar invitation attached. It takes no body. The email goes out as `config.fromEmail`, so the call needs `emails:send` beside `calendar:write`. `list` with `view` `pending` reads the bookings that wait. - Scopes: `calendar:write`, `emails:send`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Booking id such as `bkg_2b8d4f6a1c3e5079b6d8f0a2`, as `list` returns it. **Examples** ```bash nextmail bookings approve bkg_2b8d4f6a1c3e5079b6d8f0a2 ``` Skip the confirmation, for scripts ```bash nextmail bookings approve bkg_2b8d4f6a1c3e5079b6d8f0a2 --yes ``` Also available in: API [`POST /bookings/{id}/approve`](https://nextmail.sh/docs/api/reference/booking-pages#post-bookings-id-approve); TypeScript [`nextmail.bookings.approve()`](https://nextmail.sh/docs/sdk/reference/bookings#approve); Python [`bookings.approve()`](https://nextmail.sh/docs/python/reference/bookings#approve); Ruby [`bookings.approve`](https://nextmail.sh/docs/ruby/reference/bookings#approve); PHP [`bookings->approve`](https://nextmail.sh/docs/php/reference/bookings#approve); Go [`Bookings.Approve`](https://nextmail.sh/docs/go/reference/bookings#approve); Java [`bookings().approve`](https://nextmail.sh/docs/java/reference/bookings#approve); C# [`Bookings.ApproveAsync`](https://nextmail.sh/docs/csharp/reference/bookings#approve). ### `nextmail bookings decline` Turn down a booking that waits for approval ```bash nextmail bookings decline [flags] ``` Turns down a booking that waits for approval and frees its time, so the page offers that time again. The guest is told by email, sent from the address of the page, with `reason` in it when one is given. Call it with no body to decline without a reason. The email goes out as `config.fromEmail`, so the call needs `emails:send` beside `calendar:write`. - Scopes: `calendar:write`, `emails:send`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Booking id such as `bkg_2b8d4f6a1c3e5079b6d8f0a2`, as `list` returns it. **Flags** - `--reason `: A sentence for the guest, trimmed, at most 500 characters, included in the email they get. Left out or null, the email gives no reason. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash nextmail bookings decline bkg_2b8d4f6a1c3e5079b6d8f0a2 ``` With optional flags ```bash nextmail bookings decline bkg_2b8d4f6a1c3e5079b6d8f0a2 --reason 'I am away that week. Please pick a time after the 20th.' ``` Skip the confirmation, for scripts ```bash nextmail bookings decline bkg_2b8d4f6a1c3e5079b6d8f0a2 --yes ``` Also available in: API [`POST /bookings/{id}/decline`](https://nextmail.sh/docs/api/reference/booking-pages#post-bookings-id-decline); TypeScript [`nextmail.bookings.decline()`](https://nextmail.sh/docs/sdk/reference/bookings#decline); Python [`bookings.decline()`](https://nextmail.sh/docs/python/reference/bookings#decline); Ruby [`bookings.decline`](https://nextmail.sh/docs/ruby/reference/bookings#decline); PHP [`bookings->decline`](https://nextmail.sh/docs/php/reference/bookings#decline); Go [`Bookings.Decline`](https://nextmail.sh/docs/go/reference/bookings#decline); Java [`bookings().decline`](https://nextmail.sh/docs/java/reference/bookings#decline); C# [`Bookings.DeclineAsync`](https://nextmail.sh/docs/csharp/reference/bookings#decline). ### `nextmail bookings cancel` Cancel a booked meeting ```bash nextmail bookings cancel [flags] ``` Cancels a meeting that has not ended yet and cancels its calendar event. The guest is told by email, sent from the address of the page with the cancellation attached, and with `reason` in it when one is given. Call it with no body to cancel without a reason. A booking that still waits for approval is declined instead, so it ends as `declined`, not `cancelled`. The email goes out as `config.fromEmail`, so the call needs `emails:send` beside `calendar:write`. - Scopes: `calendar:write`, `emails:send`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Booking id such as `bkg_2b8d4f6a1c3e5079b6d8f0a2`, as `list` returns it. **Flags** - `--reason `: A sentence for the guest, trimmed, at most 500 characters, included in the email they get. Left out or null, the email gives no reason. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash nextmail bookings cancel bkg_2b8d4f6a1c3e5079b6d8f0a2 ``` With optional flags ```bash nextmail bookings cancel bkg_2b8d4f6a1c3e5079b6d8f0a2 --reason 'Something urgent came up. Please book another time.' ``` Skip the confirmation, for scripts ```bash nextmail bookings cancel bkg_2b8d4f6a1c3e5079b6d8f0a2 --yes ``` Also available in: API [`POST /bookings/{id}/cancel`](https://nextmail.sh/docs/api/reference/booking-pages#post-bookings-id-cancel); TypeScript [`nextmail.bookings.cancel()`](https://nextmail.sh/docs/sdk/reference/bookings#cancel); Python [`bookings.cancel()`](https://nextmail.sh/docs/python/reference/bookings#cancel); Ruby [`bookings.cancel`](https://nextmail.sh/docs/ruby/reference/bookings#cancel); PHP [`bookings->cancel`](https://nextmail.sh/docs/php/reference/bookings#cancel); Go [`Bookings.Cancel`](https://nextmail.sh/docs/go/reference/bookings#cancel); Java [`bookings().cancel`](https://nextmail.sh/docs/java/reference/bookings#cancel); C# [`Bookings.CancelAsync`](https://nextmail.sh/docs/csharp/reference/bookings#cancel). ### `nextmail bookings resend-email` Send the guest the email about their booking again ```bash nextmail bookings resend-email [flags] ``` Sends the guest the email that matches where the booking stands now: the request while it waits for approval, the confirmation with its invitation once it is confirmed, or the notice that it was declined or cancelled, with the reason that was given. Use it when `guestMailFailed` is true. It takes no body and changes nothing else about the booking. - Scopes: `calendar:write`, `emails:send`. - Needs a sign-in. **Arguments** - `` (required): Booking id such as `bkg_2b8d4f6a1c3e5079b6d8f0a2`, as `list` returns it. **Examples** ```bash nextmail bookings resend-email bkg_2b8d4f6a1c3e5079b6d8f0a2 ``` Print the raw JSON ```bash nextmail bookings resend-email bkg_2b8d4f6a1c3e5079b6d8f0a2 --json ``` Also available in: API [`POST /bookings/{id}/resend`](https://nextmail.sh/docs/api/reference/booking-pages#post-bookings-id-resend); TypeScript [`nextmail.bookings.resendEmail()`](https://nextmail.sh/docs/sdk/reference/bookings#resendEmail); Python [`bookings.resend_email()`](https://nextmail.sh/docs/python/reference/bookings#resendEmail); Ruby [`bookings.resend_email`](https://nextmail.sh/docs/ruby/reference/bookings#resendEmail); PHP [`bookings->resendEmail`](https://nextmail.sh/docs/php/reference/bookings#resendEmail); Go [`Bookings.ResendEmail`](https://nextmail.sh/docs/go/reference/bookings#resendEmail); Java [`bookings().resendEmail`](https://nextmail.sh/docs/java/reference/bookings#resendEmail); C# [`Bookings.ResendEmailAsync`](https://nextmail.sh/docs/csharp/reference/bookings#resendEmail). ### `nextmail bookings analytics` Read how the booking pages did over a window ```bash nextmail bookings analytics [flags] ``` Returns the numbers behind the Analytics tab of Booking in one request: 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. A booking counts in the window it was made in, whatever its meeting time. `totals.booked` is every booking made in the window, and `confirmed`, `pending`, `expired`, `declined` and `cancelled` split it by what became of each one, so they add up to `booked`. `cancelledByGuest` and `cancelledByHost` split `cancelled`, `rescheduled` counts the meetings moved at least once, and `minutesBooked` adds up the length of the confirmed meetings. `upcoming` ignores the window: it counts the confirmed meetings that have not ended and the requests still waiting, and gives the start of the next meeting. `series` is sparse and oldest first, so a chart must fill the gaps. `grain` sets the bucket width and the key shape, `YYYY-MM-DD`, `YYYY-MM-DDTHH` or `YYYY-MM-DDTHH:MM`, and `--offset-minutes` shifts the boundaries and the weekdays so days break where the reader's day does. `--page-ids` narrows everything to some pages, such as one page for its own Analytics tab. - Scopes: `calendar:read`. - Needs a sign-in. **Flags** - `--page-ids ` (repeatable): Count only these booking pages, at most 25, such as `['bkp_5c1e9a7b3d2f48e6a0b4c7d1']`. Every page of the person when left out. - `--days `: How far back to look, from 1 to 1095, defaulting to 30. - `--minutes `: The window in minutes, from 1 to 1576800, which wins over `days` when both are sent. - `--grain `: Bucket width: `minute`, `hour` or `day`, defaulting to `day`. - `--offset-minutes `: Minutes 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. **Examples** ```bash nextmail bookings analytics ``` With optional flags ```bash nextmail bookings analytics --days 90 ``` Print the raw JSON ```bash nextmail bookings analytics --json ``` Also available in: API [`GET /bookings/analytics`](https://nextmail.sh/docs/api/reference/booking-pages#get-bookings-analytics); TypeScript [`nextmail.bookings.analytics()`](https://nextmail.sh/docs/sdk/reference/bookings#analytics); Python [`bookings.analytics()`](https://nextmail.sh/docs/python/reference/bookings#analytics); Ruby [`bookings.analytics`](https://nextmail.sh/docs/ruby/reference/bookings#analytics); PHP [`bookings->analytics`](https://nextmail.sh/docs/php/reference/bookings#analytics); Go [`Bookings.Analytics`](https://nextmail.sh/docs/go/reference/bookings#analytics); Java [`bookings().analytics`](https://nextmail.sh/docs/java/reference/bookings#analytics); C# [`Bookings.AnalyticsAsync`](https://nextmail.sh/docs/csharp/reference/bookings#analytics). ### `nextmail bookings reschedule` Move a booked meeting to a new time ```bash nextmail bookings reschedule --start [flags] nextmail bookings reschedule --data [flags] ``` Moves a meeting that has not started to a new time and moves its calendar event with it. The meeting keeps its length, so only `start` is sent. The time has to be one the page offers for this booking: `listTimes` with `bookingId` lists them, counting the current time of the booking as free. The page may be paused, and the cut-off that limits guests does not apply to the host. The guest is told by email, sent from the address of the page with the updated invitation attached and with `reason` in it when one is given, and so is everyone the guest added. The host gets a copy at the same address unless `config.notifyHost` is false. A booking that waited for approval is confirmed at the new time, because the host chose it. The email goes out as `config.fromEmail`, so the call needs `emails:send` beside `calendar:write`. - Scopes: `calendar:write`, `emails:send`. - Needs a sign-in. **Arguments** - `` (required): Booking id such as `bkg_2b8d4f6a1c3e5079b6d8f0a2`, as `list` returns it. **Flags** - `--start `: The new start, as a `Date` or an ISO 8601 string. It has to be one of the times `listTimes` returns for the page with this `bookingId`. Required, here or in `--data`. - `--reason `: A sentence for the guest, trimmed, at most 500 characters, included in the email about the new time. Left out or null, the email gives no reason. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash nextmail bookings reschedule bkp_5c1e9a7b3d2f48e6a0b4c7d1 --start 2026-10-01T00:00:00Z ``` With optional flags ```bash nextmail bookings reschedule bkp_5c1e9a7b3d2f48e6a0b4c7d1 --start 2026-10-01T00:00:00Z --reason 'Something came up, so I moved us to the next free time.' ``` Read the whole body from a JSON file ```bash nextmail bookings reschedule bkp_5c1e9a7b3d2f48e6a0b4c7d1 --data @booking.json ``` Also available in: API [`POST /bookings/{id}/reschedule`](https://nextmail.sh/docs/api/reference/booking-pages#post-bookings-id-reschedule); TypeScript [`nextmail.bookings.reschedule()`](https://nextmail.sh/docs/sdk/reference/bookings#reschedule); Python [`bookings.reschedule()`](https://nextmail.sh/docs/python/reference/bookings#reschedule); Ruby [`bookings.reschedule`](https://nextmail.sh/docs/ruby/reference/bookings#reschedule); PHP [`bookings->reschedule`](https://nextmail.sh/docs/php/reference/bookings#reschedule); Go [`Bookings.Reschedule`](https://nextmail.sh/docs/go/reference/bookings#reschedule); Java [`bookings().reschedule`](https://nextmail.sh/docs/java/reference/bookings#reschedule); C# [`Bookings.RescheduleAsync`](https://nextmail.sh/docs/csharp/reference/bookings#reschedule).