Shipmail

Return Shipmail API health and version.

無需輸入參數。

Check whether the organization can create mailboxes now: plan, has_access, trial state and end, trial eligibility, mailbox limit and usage, and whether newsletters are allowed. Poll it after the owner opens the billing link: access appears once Shipmail has recorded the payment. Never choose or pay for a plan yourself.

無需輸入參數。

List domains in the authenticated Shipmail organization.

Fetch one domain, including verification state and registration metadata.

Return the DNS records Shipmail requires for this domain and live observed values for propagation diagnostics. A connected domain needs four: MX, SPF, DKIM and DMARC. A domain bought through Shipmail also lists two mail-subdomain records, which Shipmail adds itself. This does not update domain state.

Get a domain's health: whether its MX, SPF, DKIM and DMARC records pass, whether Spamhaus lists the domain, and the last 30 days of delivery from its mailboxes, split by recipient provider (Gmail, Outlook, Yahoo, iCloud, other).

Add an existing domain to Shipmail. This does not purchase a domain; it creates DNS records and verification state.

Route unmatched mail for a verified domain to any active mailbox in the same organization, including a mailbox on another domain. Changing the catch-all retargets all unmatched-recipient mail.

Delete a domain from Shipmail. This is destructive and cascades related mailboxes and settings.

Check current DNS and outbound verification for a domain. This may update Shipmail verification state.

Search available domains through Shipmail. This is read-only and does not purchase anything.

List mailboxes, optionally filtered by domain.

Fetch mailbox metadata and auto-reply settings.

List app-password metadata for one mailbox. Secret values are never returned by this read operation.

Create a revocable mailbox credential for an email client. The secret appears once in the tool result.

Permanently revoke one mailbox app password. The associated client will lose access immediately.

List the active SMTP credentials of the organization's transactional senders, newest first, or of one sender with from. Passwords are never returned.

Create an SMTP credential that sends as one transactional sender's address, for an SMTP client such as Supabase Auth. Its messages count as transactional email from that sender, like an API send. A sender has at most 5. The password appears once in the tool result.

Permanently revoke one SMTP credential. SMTP clients that use it can no longer send.

Manually suspend a mailbox. Authentication, sending, receiving, and Assistant automation execution are blocked until the manual suspension is removed.

Remove a mailbox's manual suspension. Billing, security, reputation, or AWS restrictions remain active independently.

Create a mailbox on an existing domain.

Create a private ZIP snapshot of one mailbox. The export runs in the background and returns a short-lived download URL when complete.

Read one mailbox export job. A completed response includes a private download URL that expires in at most five minutes.

Start an IMAP import from another provider into a Shipmail mailbox. The source accepts an app, device, or IMAP password. Outlook imports require the dashboard's Microsoft sign-in. Imports run in the background.

List recent imports for a mailbox with their status and counters.

Fetch one import with live progress counters and the per-folder report.

Stop a running import. Mail already imported stays in the mailbox. Uploaded source files and the durable cursor are retained.

Resume a stopped uploaded-file import from its durable cursor without uploading the source again.

Rebind matching staged replacement files to a cancelled or failed uploaded import. The same import job resumes from its durable cursor.

Queue deletion of messages created by an import. Mail that already existed in the mailbox is not touched.

Update a mailbox display name or API-agent security hold setting.

Delete a mailbox. This is destructive.

List system and custom folders for a mailbox, including unread counts and folder IDs for inbox rules and Assistant automations.

List deterministic server-side inbox rules and destination folders for a mailbox.

Fetch one deterministic inbox rule by exact rule ID for a mailbox.

Create one deterministic server-side inbox rule. Rules change future inbound mail handling. Custom folder targets belong to the mailbox.

Update one deterministic inbox rule by exact rule ID. Custom folder targets belong to the mailbox. expected_position detects concurrent reordering.

Delete one deterministic inbox rule by exact rule ID. Bulk deletion is unavailable. expected_position detects concurrent reordering.

Create a custom folder or subfolder for a mailbox.

Rename a custom mailbox folder. System folders cannot be renamed. Inbox rules and Assistant automations keep the stable folder ID.

Delete a custom mailbox folder. Deletion moves its remaining messages to Trash and returns a conflict while an inbox rule or automation references it.

List JMAP sending identities for a mailbox.

List inbound/JMAP message summaries with headers, preview, folders, keywords, and cursor, date, folder, keyword, search, from, to, subject, and attachment filters. Without a folder filter it lists every folder, Junk included. With one, junk_total counts matching messages held in Junk: check it before concluding that a message has not arrived.

Fetch full inbound thread messages for a mailbox, including body parts and attachment metadata. thread_id accepts a conversation ID or mail-server thread ID; responses include the stable conversation_id and version, the conversation version a reply draft takes as expected_version.

Fetch one exact JMAP inbox message.

Release the exact inbox message snapshot inspected by a security reviewer. Fetch the message first and pass its security.content_sha256. A changed snapshot returns a conflict.

Fetch one attachment from an exact JMAP inbox message. Decodable text attachments are returned in attachment.text; other attachments are embedded resources. The input uses the attachment part ID.

List deterministic inbox thread attention states with keyset cursors. Defaults to needs_reply and oldest first.

Complete, reopen, or schedule follow-up for one inbox thread using its current version. `thread_id` accepts a conversation ID (thd_...) or a thread ID.

Save a new email, rather than a reply, in the mailbox's Drafts folder. It sends nothing, and this MCP has no send operation for it. Supported HTML: p, br, strong/b, em/i, u, s, a (http, https, mailto, tel), ul, ol, li, blockquote, code, pre, h2, h3, span/mark with the composer's styles, and inline cid: images. h1 becomes h2. Tables and h4-h6 are not supported: their text stays as paragraphs and removed_formatting lists them ('table' for any table part, 'h4', ...), as it lists other dropped elements such as script, style or iframe. Attributes and inline styles outside the composer set are dropped and not reported. Paragraphs are already spaced like the Shipmail composer, so do not add <p><br></p> between them. When html is given without text, the text part is derived from it.

Create a server-recipient-derived reply draft against a thread version. This does not send email. expected_version is the version field of the inbox thread read or the inbox thread queue. Supported HTML: p, br, strong/b, em/i, u, s, a (http, https, mailto, tel), ul, ol, li, blockquote, code, pre, h2, h3, span/mark with the composer's styles, and inline cid: images. h1 becomes h2. Tables and h4-h6 are not supported: their text stays as paragraphs and removed_formatting lists them ('table' for any table part, 'h4', ...), as it lists other dropped elements such as script, style or iframe. Attributes and inline styles outside the composer set are dropped and not reported. Paragraphs are already spaced like the Shipmail composer, so do not add <p><br></p> between them. When html is given without text, the text part is derived from it.

List a conversation's reply drafts in every status (draft, sending, sent, invalidated, failed), newest first, at most 100. html, text and subject are null once the stored draft no longer exists.

Read one reply draft with its status, recipients, subject and stored html and text. Use it to check a draft before sending it.

Replace the body of a reply draft in status draft. This does not send email. The new body replaces the old one: html alone derives the text part, text alone makes a plain-text draft. Recipients, subject and reply headers stay derived from the source message, and the draft ID stays the same. Returns a conflict when the draft is not in status draft, when the thread changed since its expected_version (the draft becomes invalidated: read the thread again and create a new draft), when the draft changed concurrently, or when it belongs to the Shipmail Assistant. Supported HTML: p, br, strong/b, em/i, u, s, a (http, https, mailto, tel), ul, ol, li, blockquote, code, pre, h2, h3, span/mark with the composer's styles, and inline cid: images. h1 becomes h2. Tables and h4-h6 are not supported: their text stays as paragraphs and removed_formatting lists them ('table' for any table part, 'h4', ...), as it lists other dropped elements such as script, style or iframe. Attributes and inline styles outside the composer set are dropped and not reported. Paragraphs are already spaced like the Shipmail composer, so do not add <p><br></p> between them. When html is given without text, the text part is derived from it.

Delete a reply draft in status draft, invalidated or failed, and remove it from the Drafts folder. Drafts that are sending or sent, and drafts that belong to the Shipmail Assistant, return a conflict.

Send one previously created safe reply draft. Pass expected_content_sha256 from the exact draft the user approved. Stale, edited, or concurrently updated drafts return a conflict.

Reply to a JMAP inbox message within its mailbox.

Reply to a JMAP inbox thread within its mailbox.

Set read and/or starred state on one inbox message.

Move one inbox message to a system folder role or custom folder ID.

Permanently delete one inbox message in Trash or Junk. Messages outside those folders cannot be deleted.

List pending and active forwarding destinations for a mailbox.

Send a confirmation email to a forwarding destination. Optionally filter by exact From address, delivery recipient, or both. Delivery begins after confirmation, keeps a local copy, and excludes spam.

Remove a pending or active mailbox forwarding destination.

Reset a mailbox login password with the supplied replacement password.

Configure automatic replies to incoming mail for a mailbox.

Read how new messages sent to a mailbox's primary address are kept, delivered to one mailbox, or distributed among mailboxes. Aliases bypass this routing.

Choose where new primary-address conversations are delivered. Fixed and round-robin modes require an explicit fallback mailbox; out-of-office mailboxes are skipped for new selections.

無需輸入參數。

Create a fake inbound message in isolated sandbox storage. Requires a test API key and never sends mail to the supplied addresses.

Atomically capture a completed, snapshot-consistent set of reply-needed threads in a date window. Results are retained for 30 days.

Retrieve completed historical reply scan metadata and its candidate count.

Page through a completed historical reply scan using an opaque cursor.

List recent messages by mailbox or organization-scoped client reference.

List an organization-wide, analytics-safe message projection in stable updated_at order. The response excludes subjects, BCC addresses, headers, free-form metadata, attachment filenames, and message bodies. contact_addresses and caller-defined client_reference values may contain personal data.

Fetch one message by ID.

Open a review card for a conversation or library file when the host supports MCP Apps file handoff and widget tool calls. The component sends or schedules only after the user presses its action.

Create a five-minute, one-time raw upload URL bound to the mailbox, filename, content type, byte size, and SHA-256 digest. The upload returns a staged attachment ID.

Send an email from a mailbox ID, with optional durable client correlation, scalar metadata, and validated safe headers. Give subject with html or text, or give template ({ id, version?, variables? }) to send a stored template; with template, omit subject, html and text.

List future scheduled messages. Set include_held to include undo-send holds that have not begun dispatch.

Inspect one future scheduled message or undo-send hold, including its recipients, body, and attachment metadata.

Replace the recipients, content, staged attachments, and delivery time of a future scheduled message before dispatch begins.

Cancel one future scheduled message or undo-send hold before dispatch begins. Delivery cannot be cancelled after dispatch starts.

Reply to a stored Shipmail message whose ID starts with msg_.

Accept, tentatively accept or decline the calendar invitation a received message carries, by its msg_ ID. Stores the answer on the mailbox calendar and replies to the organizer only when the organizer sent the message. The message.received webhook's invitation field says which messages carry one.

List thread summaries in a mailbox. Each row includes a thread ID and stable conversation_id.

Fetch messages in a thread by conversation ID or mail-server thread ID. Each message includes its stable conversation_id.

Reply to a stored Shipmail thread within its required mailbox scope. Accepts a conversation ID or mail-server thread ID.

List organization members and their mailbox access. Selected mailbox IDs are limited to mailboxes visible to this API credential and may be partial.

Fetch an organization member and their mailbox access by ID. Selected mailbox IDs are limited to mailboxes visible to this API credential and may be partial.

List pending, unexpired invitations to join the organization, newest first. Selected mailbox IDs are limited to mailboxes visible to this API credential and may be partial.

無需輸入參數。

Invite a person to the organization as an admin or member. The invitee receives an email and creates their own account; no credential is returned. Share only the mailboxes they need with mailbox_ids; "all" is allowed only when the person behind this credential reads every mailbox and the credential is not restricted. Needs the members:write permission, which is opt-in and never part of a default. It acts with the authority of the person who approved this connection or created the API key.

Cancel a pending invitation so its link stops working. Needs the members:write permission, which is opt-in and never part of a default. It acts with the authority of the person who approved this connection or created the API key.

Share one mailbox with a member who has selected mailbox access. You can only share mailboxes the person behind this credential reads. Sharing an already shared mailbox changes nothing. Needs the members:write permission, which is opt-in and never part of a default. It acts with the authority of the person who approved this connection or created the API key.

Stop sharing one mailbox with a member. Their credentials that reached only through that mailbox are revoked. Removing a mailbox that is not shared changes nothing. Needs the members:write permission, which is opt-in and never part of a default. It acts with the authority of the person who approved this connection or created the API key.

List webhook endpoints configured for the organization.

Fetch webhook endpoint configuration by ID.

Create a webhook endpoint. Its signing secret appears once in the tool result and conversation log. Optional authorization is sent as the Authorization header of every delivery, and optional standard_webhooks_secret signs every delivery the way Standard Webhooks receivers such as Grok automations check. Both are write-only and never echoed back, but the values you pass appear in the conversation log.

Update webhook URL, subscribed events, description, active state, mailbox and domain filter, the Authorization header sent with deliveries, the Standard Webhooks signing secret, whether message.received carries reply_text, whether it skips unauthenticated senders, or the senders it is limited to. A URL change redirects future deliveries. authorization and standard_webhooks_secret are write-only and never echoed back; null removes them.

Delete a webhook endpoint. This is destructive.

Rotate a webhook signing secret. Integrations using the old secret stop verifying after previous_secret_expires_at. The replacement appears once in the conversation log.

Queue a test event for a webhook endpoint.

List delivery attempts for a webhook endpoint.

Fetch one webhook delivery, including its payload and replay source.

Queue one failed webhook delivery again.

List event queues configured for the organization. An event queue stores the same events a webhook would deliver, for an agent to read with its API key instead of receiving them at a public URL.

Fetch an event queue's configuration by its evq_ ID.

Create an event queue: it stores the chosen events (message.received, message.bounced, booking events, reply.overdue and the rest of the webhook events) for you to read with your API key, so no public URL is needed. It only gets events that happen after it is created. Up to 10 per organization. There is no update: delete and recreate to change a filter.

Delete an event queue and every event it still holds. This is destructive.

Read the oldest unacknowledged events of an event queue, oldest first. Each event is the same envelope a webhook delivery carries (version, event_id, event_type, created_at, test, data). Reading changes nothing: handle the events, then acknowledge their event_id values, and read again while has_more is true. Delivery is at least once, so skip event_id values already handled. Events not acknowledged within 30 days are deleted.

Acknowledge handled events by their event_id, which deletes them from the event queue. Idempotent: unknown or already acknowledged IDs are ignored. Returns how many events were deleted.

List suppressed recipients. Each entry has a reason (hard_bounce, complaint, soft_bounce or manual), a scope (all blocks every send; a complaint blocks only its own kind of email: marketing for newsletters, transactional for application senders, mailbox for mail sent from a mailbox) and expires_at (null when permanent; soft-bounce pauses last 30 days).

Suppress an email address so nothing more is sent to it (reason manual). scope all (the default) blocks every send; marketing blocks newsletter sends only. If an active entry already covers the address it is returned, with its scope widened to all when asked; a permanent entry is never shortened.

Remove one email address from the suppression list.

List customers. Filter by an exact email or domain identifier, by an external ID (external_source with external_id), by a tag, or search name, company and identifiers with q; filters combine. Each customer carries its reply time (service_level_id), tags, notes, fields, identifiers and external IDs.

Fetch one customer by ID, such as the customer_id of an inbox conversation.

Create a customer with its email addresses or domains. Conversations from a matching, verified sender get the customer's reply time, notes and fields. An address or domain owned by another customer is refused with identifier_conflict.

Change a customer. Only the properties you pass change; identifiers, external_ids, fields and tags replace the stored set when given. Changing service_level_id moves the reply clocks of the customer's open conversations.

Delete a customer with its identifiers and external IDs. Its conversations fall back to the mailbox default reply time. This is destructive.

Create or update the customer a CRM or billing system knows by source and external_id. Calling it again with the same values changes nothing. An address or domain owned by another customer is refused with identifier_conflict and that customer's ID; it is never moved.

List the reply times a customer can have: each promises a reply within reply_target_minutes, counted inside business_hours when set.

無需輸入參數。

List the custom fields a customer can carry, with their key, label and type.

無需輸入參數。

List stored email templates. Each has a draft (subject, html, text, fallbacks), the {{key}} variables it uses, published_version (the version sends use, null until published) and has_unpublished_changes.

Get one template's draft, its variables (required ones have no fallback and must be passed on every send) and its published version.

Create an email template. subject, html and text may use {{key}} variables; fallbacks gives a default per key, and a key without one must be passed on every send. Values are inserted as text, never as HTML. The template is a draft until published: set publish to true, or publish it later, before sending it.

Change a template's draft: name, subject, html, text or fallbacks. Sends keep using the published version until the template is published again. Null removes html or text; at least one must remain.

Delete a template and all its versions. Sends that name it fail afterwards. This is destructive.

Publish a template's draft as its next version. Sends that do not pin a version use it from then on. Earlier versions stay available.

Render a template with variables and return the subject, html and text a send would use. Renders the draft unless version is given. Nothing is stored or sent. A missing required variable fails with the keys it needs.

List a template's published versions, newest first. Each is an immutable snapshot of subject, html, text and fallbacks.

Get one published version of a template.

Copy a published version into the template's draft, replacing the current draft. It does not publish: publish the template to make sends use it.

List newsletter drafts and sends in the authenticated Shipmail organization.

List configured newsletter sending domains and their verification status in the authenticated Shipmail organization.

List configured newsletter sender identities and their IDs.

List reusable newsletter images and videos with their asset IDs.

Register an existing Shipmail-hosted image or video URL as a reusable newsletter asset without re-uploading bytes.

Open a review card for a conversation or library image or video when the host supports MCP Apps file handoff. The component uploads only after the user presses its action.

Create a five-minute direct newsletter media upload bound to the organization, filename, content type, byte size, and SHA-256 digest. Object and completion URLs are single-use. Video uploads include a JPEG poster upload.

Fetch one newsletter draft or send by ID, including content, delivery counters, and lifecycle timestamps.

Render a newsletter draft into sanitized email HTML, archive HTML, text, warnings, and counted URL breakdown.

Create a newsletter draft for an audience and sender identity. Shipmail renders blocks to email-safe HTML and text. Pass content_markdown to write the body in Markdown instead; it is converted to blocks. Paragraph, quote, callout, list-item, and column bodies accept text or sanitized inline HTML. styled applies Shipmail's email theme. plain preserves HTML without injected styles, width, or centering. track_engagement turns on open and click tracking for this issue; it is off by default.

Create a newsletter draft from changelog entries, attached media, tone, and an optional final CTA. Shipmail renders entries into email-safe blocks. styled applies Shipmail's email theme. plain preserves HTML without injected styles, width, or centering.

Update an editable newsletter draft or future scheduled newsletter. Changing message content, presentation, or audience returns a scheduled newsletter to draft and clears scheduled_at; inspect the returned status, send a new test, and schedule again. Name, feed link, and send-window changes can keep the schedule. content_markdown replaces the body with blocks converted from Markdown. Paragraph, quote, callout, list-item, and column bodies accept text or sanitized inline HTML. body_text alone updates the plain-text override when blocks exist. Sending and sent newsletters cannot be edited. Concurrent saves return conflict (409). styled applies Shipmail's email theme. plain preserves HTML without injected styles, width, or centering. track_engagement turns open and click tracking on or off for this issue.

Run preflight checks for one newsletter.

Send a newsletter test email to one recipient.

Schedule a newsletter for delivery to its audience.

Send a newsletter that was scheduled with a limit to the next most engaged subscribers it held, or to all of them. Nobody gets the newsletter twice. held_count on the newsletter says how many are waiting.

Cancel a scheduled, paused, or sending newsletter. Already sent messages cannot be recalled.

Resume a paused newsletter delivery.

List newsletter audiences in the authenticated Shipmail organization, with member and subscribed counts.

Fetch one newsletter audience, including member and subscribed counts.

Create a newsletter audience. consent_source is a required attestation of where and how these people opted in.

Update a newsletter audience's name or description.

Delete a newsletter audience. Destructive: cascades all its subscribers. Newsletters keep their history.

Fetch an audience's Atom feed settings and current URL. Anyone with the URL can read the feed.

Enable or disable an audience's Atom feed, update its public metadata and canonical URL, or set its 10 to 100 entry limit.

Generate a replacement feed URL. The current URL redirects to it until the next rotation, which permanently breaks the oldest URL.

Immediately disable the current and every previous feed URL, then return a replacement. Existing readers must subscribe again.

List an audience's saved segments with their rules and how many subscribed members each matches now. A segment's id is what segment_id takes in a block's visibility: show the block only to readers in it, or to everyone except them.

Fetch one saved segment of an audience with its rules and how many subscribed members it matches now.

Save a segment of an audience: a name unique in the audience and 1 to 10 rules on merge fields, join date, engagement tier, last sign of life or issues received, matched all or any. Sends nothing. Use the returned id as segment_id in a block's visibility.

Rename a segment, replace its rules, or both. A newsletter not yet scheduled uses the new rules; a scheduled one keeps the readers fixed when it was scheduled.

Delete a saved segment. Refused with a 409 conflict while any newsletter of the audience sends to it, which only the dashboard can set. A block limited to it does not stop the delete, but a draft with such a block then fails preflight until the block is changed.

Fetch an audience's welcome sequence: whether it runs or paused, its emails in order with their waits and send counts, and how many readers are in it.

Turn an audience's welcome sequence on or off. While it is on, every reader who subscribes through a signup form or the API (or confirms, with double opt-in) gets its emails, at most 100 per audience in any ten minutes. Turning it on also resumes a sequence paused on bounces or complaints.

Add an email to the end of an audience's welcome sequence, written as blocks or content_markdown. wait_minutes counts from the previous email, or from the subscribe for the first one. When the sequence is on, readers in it get this email.

Change a welcome email's subject, body (blocks or content_markdown), sender, tracking or wait. Readers already past it are not affected.

Remove an email from a welcome sequence. Readers waiting for it go on to the next email. A running sequence keeps at least one email.

List subscribers in a newsletter audience. Filter by status or an exact email address.

Fetch one subscriber in an audience by its subscriber ID.

Look up a subscriber in an audience by email address.

Add one subscriber to an audience (single opt-in). Returns a per-row outcome (created, updated, or a skip reason); it never throws for a suppressed or invalid address.

Add up to 1000 subscribers to an audience in one call (single opt-in). Returns a per-row outcome for each address.

Update a subscriber's display name or merge fields.

Unsubscribe a subscriber. Writes an organization-wide opt-out so future newsletters skip them.

Resubscribe a subscriber after renewed opt-in. Removes their organization-wide newsletter opt-out and marks them active again.

Send the double opt-in confirmation email again to pending subscribers of an audience. Each call emails real subscribers. Without subscriber_ids it emails every eligible pending subscriber, at most 500 per call; remaining says how many are left. A subscriber is emailed only when they signed up at most 30 days ago, had fewer than 3 resends, and got no confirmation email in the last 24 hours. Each email carries a new link valid 7 days, and the old link stops working.

Permanently delete a subscriber row from an audience. This hard-deletes the row and does not preserve opt-out history.

List calendar events in a time range for one mailbox. expand=true returns recurring events as individual instances.

Fetch one calendar event by ID for a mailbox.

Create a calendar event on a mailbox's calendar. start is a local date-time; its zone is given by timezone. Reuse operation_key only when retrying the exact same payload.

Update a calendar event. Omitted fields are unchanged; send null to clear description, timezone, location, video_url, recurrence, or reminders. Use expected_revision from a prior read and reuse operation_key only for an exact-payload retry.

Delete a calendar event by ID for a mailbox.

Compute open meeting slots for one mailbox from its own calendar. Single-mailbox only; not a cross-user free/busy lookup.

List assistant automations visible to this API key's mailbox constraints.

無需輸入參數。

Fetch one assistant automation by ID.

Create and activate an assistant automation from an explicit reviewed definition. This persists behavior until paused or disabled.

Change an automation's name, reviewed definition, or status. Definition changes create and activate a new immutable version.

Queue one run of a manual automation.

List booking pages in the authenticated organization.

Fetch one booking page by ID.

Create a booking page exposing one mailbox's availability. availability_days is 0=Sunday..6=Saturday. conferencing_provider is opt-in and must already be connected to the mailbox.

Update a booking page. All fields optional; provide at least one. Set conferencing_provider to null to stop creating meeting links.

Delete a booking page by ID.

List one-off booking links in the authenticated organization, newest first. Filter by status: open, booked (used all of max_bookings), expired or revoked.

Fetch one one-off booking link by ID, with its public URL, offered times, bookings taken and status.

Create a one-off booking link for one mailbox. Only create one when the user asked for it. It offers offered_ranges, or the weekly hours of source_page_id. The link stops taking bookings after max_bookings (default 1, null means unlimited) and after expires_at. Share the returned url with the person who should book.

Update a one-off booking link that is not revoked. Fields left out keep their value; provide at least one. The link stops taking bookings after max_bookings (null means unlimited). The url and the bookings already taken stay.

Revoke a one-off booking link so it takes no more bookings. Only revoke when the user asked for it. This cannot be undone; the link stays readable with status revoked, and bookings already made are kept.