Communications & Productivity

Upload an attachment

Content-addresses an attachment to object storage under the caller's org/mailbox prefix. The caller must pass `mailboxId` as a query parameter and send the raw file bytes as the request body (`application/octet-stream`). Returns the SHA-256 content hash and byte length; pass the `sha256` in a subsequent send request. The per-file limit is 25 MiB. Returns `413 Payload Too Large` when the declared `Content-Length` or actual body exceeds 25 MiB.

Auth Session JWT (Bearer)

Parameters

Responses

Stream an attachment

Streams a previously-uploaded attachment by its SHA-256 content hash. The `mailboxId` query parameter is required. Non-executable content types are served inline with `nosniff`; all others are served as `application/octet-stream` with `Content-Disposition: attachment`.

Auth Session JWT (Bearer)

Parameters

Responses

List sending domains

Returns all mail sending domains linked to the caller's organization.

Auth Session JWT (Bearer)

Responses

Link a sending domain

Links a domain to the caller's organization for use as a mail sending domain. Returns the domain record with the DNS records that must be published to verify ownership and configure routing.

Auth Session JWT (Bearer)

Request Body

Responses

Get a sending domain

Returns a single sending domain including its verification status and required DNS records.

Auth Session JWT (Bearer)

Parameters

Responses

Auto-provision Cloudflare DNS and email routing

Drives Cloudflare DNS and Email-Routing provisioning for a Cloudflare-hosted domain. Attempts provider-based ownership proof via the organization's connected Cloudflare account before provisioning. Returns a structured per-step result in all cases; inspect the `code` field to determine the outcome (`OK`, `PARTIAL`, `OWNERSHIP_NOT_PROVEN`, `DOMAIN_NOT_ON_CLOUDFLARE`, `NEEDS_PROVIDER_CONNECTION`, `DOMAIN_ALREADY_CLAIMED`).

Auth Session JWT (Bearer)

Parameters

Responses

Onboard domain to AWS SES for sending

Drives SES identity creation, Easy-DKIM, and MAIL-FROM configuration for a verified domain. Requires a proven ownership timestamp on the domain. Returns a structured per-step result; `503` when SES is not configured server-side.

Auth Session JWT (Bearer)

Parameters

Responses

Poll SES verification status

Polls SES for send-readiness (DKIM, MAIL-FROM) and performs an MX reachability probe for receive-readiness, persisting the results. Requires proven ownership. Returns `409` when ownership is not proven.

Auth Session JWT (Bearer)

Parameters

Responses

Verify domain ownership via DNS TXT

Triggers an ownership verification check by performing a DNS-over-HTTPS lookup for the `_bbmail-verify.<domain>` TXT record and passing the observed value to the server. The server (not the route) makes the ownership decision. Returns the updated domain record with the new verification status.

Auth Session JWT (Bearer)

Parameters

Responses

Re-check published DNS records

Re-checks the live DNS records (MX, SPF, DKIM CNAME, DMARC) for a domain whose ownership has already been verified, and advances the per-record-class verification flags so the setup wizard can display per-step status. Requires `ownership_verified_at` to be set on the domain; returns `409 CONFLICT` otherwise.

Auth Session JWT (Bearer)

Parameters

Responses

List message filters

Returns all message filters defined for the specified mailbox, ordered by `ordinal`.

Auth Session JWT (Bearer)

Parameters

Responses

Create a message filter

Creates a new message filter rule in the specified mailbox. `criteria` and `actions` are structured JSON objects validated server-side.

Auth Session JWT (Bearer)

Request Body

Responses

Update a message filter

Updates one or more filter properties. `mailboxId` is required in the body.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a message filter

Deletes a message filter. The `mailboxId` query parameter is required.

Auth Session JWT (Bearer)

Parameters

Responses

Run a message filter

Authorizes and returns the validated filter specification so the mailbox Durable Object can apply it over its hot message index. The route does not mutate message state directly — mutation is handled via the WebSocket protocol in the Durable Object.

Auth Session JWT (Bearer)

Parameters

Responses

Receive inbound message via SMTP hook (public webhook)

Public MTA-hook endpoint called by the self-hosted Stalwart inbound SMTP fleet at the DATA stage. Accepts a JSON envelope containing the raw RFC 822 message, SMTP envelope, and edge-computed SPF/DKIM/DMARC verdicts signed with an HMAC. After signature verification the handler resolves the recipient address to a mailbox, durably writes the raw message to object storage (the commit point), then asynchronously writes the catalog row and projects the message index. Returns `{ action: "discard" }` on success to instruct the MTA to drop the message from its spool. A `503` response signals a temporary failure; the MTA or its local spool should retry.

Auth Provider webhook signature

Request Body

Responses

List labels

Returns all labels in the specified mailbox including their hierarchy.

Auth Session JWT (Bearer)

Parameters

Responses

Create a label

Creates a new label in the specified mailbox. Labels can be nested by supplying a `parentId`.

Auth Session JWT (Bearer)

Request Body

Responses

Update a label

Updates one or more label properties. `mailboxId` is required in the body. All other fields are optional.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a label

Deletes a label from a mailbox. The `mailboxId` query parameter is required.

Auth Session JWT (Bearer)

Parameters

Responses

List mailboxes

Returns the mailboxes the caller owns or has been delegated access to within the authenticated organization.

Auth Session JWT (Bearer)

Responses

Create a mailbox

Creates a new mailbox under a verified sending domain in the caller's organization. The organization is taken from the authenticated session and is never accepted in the request body.

Auth Session JWT (Bearer)

Request Body

Responses

List messages

Returns a paginated list of messages in the specified mailbox, optionally filtered by direction.

Auth Session JWT (Bearer)

Parameters

Responses

Get a message

Returns a single message by id. The `mailboxId` query parameter is required. A message the caller cannot access is reported as `404 NOT_FOUND`.

Auth Session JWT (Bearer)

Parameters

Responses

Apply or remove a message label (WebSocket-only operation)

Message label mutations are performed over the mailbox WebSocket (`GET /v1/bbmail/ws`), not via REST. Connect to the mailbox socket and send the `MSG_LABEL` operation; the change is applied in the mailbox Durable Object and durably audited via the signed audit flush. This REST endpoint exists to return a machine-readable error rather than silently returning `404`.

Auth Session JWT (Bearer)

Parameters

Responses

Move a message (WebSocket-only operation)

Message-folder moves are performed over the mailbox WebSocket (`GET /v1/bbmail/ws`), not via REST. Connect to the mailbox socket and send the `MSG_MOVE` operation; the change is applied in the mailbox Durable Object and durably audited via the signed audit flush. This REST endpoint exists to return a machine-readable error rather than silently returning `404`.

Auth Session JWT (Bearer)

Parameters

Responses

Send a message

Sends an outbound email from the specified mailbox. The `From` identity is resolved server-side from the mailbox record; callers cannot override it. All attachments must be pre-uploaded via `POST /v1/bbmail/attachments`; only content-addressed references (`sha256`) are accepted here. The combined `to + cc + bcc` count must not exceed the platform MAX_RECIPIENTS limit. In restricted (non-production) environments outbound recipients are checked against the org's verified domains and current org members. An optional `Idempotency-Key` header (max 256 chars) enables safe retries.

Auth Session JWT (Bearer)

Request Body

Responses

Get mailbox settings

Returns the caller's per-user preferences for the specified mailbox.

Auth Session JWT (Bearer)

Parameters

Responses

Update mailbox settings

Upserts the caller's per-user preferences for the specified mailbox. All fields are optional; only supplied fields are updated.

Auth Session JWT (Bearer)

Request Body

Responses

Open mailbox WebSocket

Upgrades an HTTP connection to a WebSocket channel connected to the caller's mailbox Durable Object. The caller must supply a one-time `token` query parameter (a short-lived JWT minted by the session) and the `mailboxId` to connect to. The server verifies the token, checks revocation, and runs the mailbox effective-access gate before forwarding the upgrade. A connection without `Upgrade: websocket` receives `426 Upgrade Required`. The capability (`read` or `write`) is derived from the access verdict and forwarded to the Durable Object, which re-verifies independently. Authentication is via the `token` query parameter (`oneTimeTicket` scheme) — a standard `Authorization` header is not supported on WebSocket upgrades.

Auth One-time ?token= ticket

Parameters

Responses

Request calendar access

Submits an access request for a calendar by id or owner email. An optional email notification can be sent to the calendar owner.

Auth Session JWT (Bearer)

Request Body

Responses

List appointment schedules

Returns the caller's appointment booking schedules. Optionally filter by `calendar_id`.

Auth Session JWT (Bearer)

Parameters

Responses

Create or update an appointment schedule

Upserts an appointment booking schedule. Supply `id` to update an existing schedule; omit to create a new one. Returns `201` on create, `200` on update.

Auth Session JWT (Bearer)

Request Body

Responses

Get an appointment schedule

Returns a single appointment booking schedule.

Auth Session JWT (Bearer)

Parameters

Responses

Get public booking page (public)

Returns the public-safe appointment schedule metadata for a booking page slug, including optionally the freebusy-level busy intervals for a `[from, to]` window (clamped server-side to 62 days). An unknown slug returns `404`. Rate-limited per IP.

Public Public: no authentication

Parameters

Responses

Create a booking (public)

Creates an appointment booking via the public booking page. Requires a valid Cloudflare Turnstile token in `cf-turnstile-response` (evaluated server-side; the field is stripped before storage). The server resolves the schedule by slug, conflict-checks the slot, and creates the event and confirmation email.

Public Public: no authentication

Request Body

Responses

Get booking details for management (public)

Resolves a per-booking management token and returns the booker-safe booking details. Internal fields (`org_id`, owner user id, created event id) are never returned. Rate-limited per IP.

Public Public: no authentication

Parameters

Responses

Cancel or reschedule a booking (public)

Cancels or reschedules a booking via the per-booking management token. Requires a valid Cloudflare Turnstile token in `cf-turnstile-response`. `reschedule` requires `starts_at`.

Public Public: no authentication

Parameters

Request Body

Responses

List calendars

Returns the calendars visible to the caller in their organization. Pass `include_hidden=true` to include hidden calendars.

Auth Session JWT (Bearer)

Parameters

Responses

Create a calendar

Creates a new calendar in the caller's organization. All fields are optional; defaults are assigned by the platform.

Auth Session JWT (Bearer)

Request Body

Responses

Get a calendar

Returns a single calendar. A calendar the caller cannot see is reported as `404 NOT_FOUND`.

Auth Session JWT (Bearer)

Parameters

Responses

Update a calendar

Updates calendar properties. All fields are optional; `name: null` clears the name.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a calendar

Deletes a calendar.

Auth Session JWT (Bearer)

Parameters

Responses

List calendar ACL entries

Returns the access-control list for a calendar. Pass `include_revoked=true` to include revoked grants.

Auth Session JWT (Bearer)

Parameters

Responses

Grant or revoke a calendar share

Adds, updates, or revokes a share grant for a calendar. Requires `can_admin` on the calendar.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Get per-calendar settings

Returns the caller's per-calendar settings.

Auth Session JWT (Bearer)

Parameters

Responses

Update per-calendar settings

Updates the caller's per-calendar settings. Body is a free-form JSON object; `org_id` and `calendar_id` are pinned from the session and path.

Auth Session JWT (Bearer)

Parameters

Request Body

Key-value settings bag; validated server-side.

Responses

List events in a time window

Returns events across the caller's visible calendars within the `[from, to]` ISO-8601 window. Recurring event masters are expanded server-side into concrete occurrences within the window. `calendars` is an optional comma-separated list of calendar UUIDs to restrict the query.

Auth Session JWT (Bearer)

Parameters

Responses

Create an event

Creates a new event (or recurring series master / override) in the specified calendar. Timing, attendees, RRULE, reminders, and conferencing are validated server-side.

Auth Session JWT (Bearer)

Request Body

Responses

Get an event

Returns a single event. The `calendar_id` query parameter is required.

Auth Session JWT (Bearer)

Parameters

Responses

Update an event

Updates event fields. `calendar_id` query parameter is required. For recurring events, `scope` controls whether the edit applies to `this` occurrence, `this_and_following`, or `all`.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete an event

Deletes an event. `calendar_id` query parameter is required. For recurring events, `scope` and `recurrence_id` control which occurrences are removed.

Auth Session JWT (Bearer)

Parameters

Responses

Move event to another calendar

Moves an event from one calendar to another within the same organization.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Publish or unpublish an event

Publishes an event to a public render token, or unpublishes it. `calendar_id` query parameter is required.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Set event reminders

Replaces the caller's reminder settings for an event.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

RSVP to an event

Records the caller's RSVP response for an event invitation. Supports proposing an alternative time.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Download ICS calendar feed (public)

Resolves a secret or public ICS feed token and returns a well-formed `text/calendar` iCalendar document. The token is validated constant-time; an invalid, revoked, or visibility-`none` token returns `404 NOT_FOUND` with no distinguishing information. Rate-limited per IP at 120 requests per minute.

Public Public: no authentication

Parameters

Responses

Query free/busy

Returns busy intervals for one or more calendars or users within the `[from, to]` window. `calendars` and `users` are optional comma-separated UUID lists.

Auth Session JWT (Bearer)

Parameters

Responses

Get a published event (public)

Resolves a high-entropy render token and returns the published, server-redacted event JSON. The token is validated constant-time; an invalid, revoked, or missing token returns `404`. The raw token is never echoed in the response.

Public Public: no authentication

Parameters

Responses

Search events

Full-text search across the caller's visible events. `q` is required; `who`, `where`, `from`, `to`, and `limit` (1–200) are optional filters.

Auth Session JWT (Bearer)

Parameters

Responses

Get account-wide calendar settings

Returns the caller's account-wide calendar preferences.

Auth Session JWT (Bearer)

Responses

Update account-wide calendar settings

Updates the caller's account-wide calendar preferences. Body is a free-form JSON object; `org_id` is pinned from the session.

Auth Session JWT (Bearer)

Request Body

Settings key-value bag.

Responses

List calendar sync connections

Returns the caller's external calendar provider connections. Optionally filter by `provider`.

Auth Session JWT (Bearer)

Parameters

Responses

Connect a calendar sync provider

Stores encrypted provider credentials and creates a sync connection. For CalDAV, supply `caldav_password` (plaintext over HTTPS); it is encrypted server-side before storage and is never returned. For Google and Microsoft, use the OAuth flow (`/sync/oauth/{provider}/start`) to obtain tokens and call this endpoint with encrypted token fields, or complete the OAuth flow directly via the OAuth callback routes.

Auth Session JWT (Bearer)

Request Body

Responses

Link a provider calendar to a BB calendar

Creates a sync link pairing an external provider calendar with a Backbuild calendar for bidirectional or one-way sync.

Auth Session JWT (Bearer)

Request Body

Responses

Remove a calendar sync link

Removes the sync link between a provider calendar and a Backbuild calendar.

Auth Session JWT (Bearer)

Parameters

Responses

Google Calendar OAuth callback (browser redirect)

Handles the Google OAuth authorization callback. Validates the CSRF `state` parameter and one-time nonce, exchanges the authorization code for tokens, encrypts them, and stores the connection. Redirects the browser to the calendar settings page with `connected=google` or `sync_error=<reason>` on failure. A `?error=access_denied` from the provider redirects immediately without a token exchange.

Auth Session JWT (Bearer)

Parameters

Responses

Google Calendar OAuth callback (SPA form post)

Same as the GET callback but for SPAs that capture the authorization code client-side and POST `{ code, state }` as a JSON body.

Auth Session JWT (Bearer)

Request Body

Responses

Start Google Calendar OAuth flow

Generates the Google consent URL for the Calendar sync OAuth flow. Returns the authorization URL and a CSRF-bound state token. The client should redirect the user to the returned `url`. Requires the `calendar` feature flag.

Auth Session JWT (Bearer)

Responses

Microsoft Calendar OAuth callback (browser redirect)

Handles the Microsoft OAuth callback — same contract as the Google GET callback.

Auth Session JWT (Bearer)

Parameters

Responses

Microsoft Calendar OAuth callback (SPA form post)

Same as the GET callback but accepts `{ code, state }` as a JSON body from an SPA.

Auth Session JWT (Bearer)

Request Body

Responses

Start Microsoft Calendar OAuth flow

Generates the Microsoft identity platform consent URL for the Calendar sync OAuth flow. Returns the authorization URL and CSRF state token. Requires the `calendar` feature flag.

Auth Session JWT (Bearer)

Responses

List provider calendars for a connection

Fetches the list of calendars from the connected external provider (Google or Microsoft) for use in the sync picker. Refreshes the access token server-side if needed; the token is never returned to the caller. CalDAV connections are not supported by this endpoint.

Auth Session JWT (Bearer)

Parameters

Responses

List task lists

Returns the caller's task lists.

Auth Session JWT (Bearer)

Responses

Create, rename, or delete a task list

Upserts a task list. `action` must be `create`, `rename`, or `delete`. `list_id` is required for `rename` and `delete`; `title` is required for `create` and `rename`.

Auth Session JWT (Bearer)

Request Body

Responses

Create a task

Creates a new task in the specified task list.

Auth Session JWT (Bearer)

Request Body

Responses

Update a task

Updates task fields. All fields are optional.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a task

Deletes a task. Pass `cascade=true` to also delete sub-tasks.

Auth Session JWT (Bearer)

Parameters

Responses

Complete or reopen a task

Marks a task completed or reopens it. Pass `{ "completed": false }` to reopen.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Move a task

Moves a task to a different list and/or changes its ordinal position.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Open calendar WebSocket

Upgrades to a WebSocket channel connected to the calendar Durable Object. The caller supplies a one-time `token` (JWT) and the `calendarId`. The server verifies the token, checks revocation, and runs the four-bit calendar access gate (`can_read_freebusy` / `can_read_details` / `can_write` / `can_admin`) before forwarding the upgrade. The derived capability (`freebusy`, `read`, or `write`) is passed to the Durable Object, which re-verifies independently. A request without `Upgrade: websocket` receives `426`.

Auth One-time ?token= ticket

Parameters

Responses

Unsubscribe confirmation page (public)

Browser-clickable GET endpoint for the RFC 2369 `List-Unsubscribe` header. Verifies the HMAC-signed `token` query parameter and renders a confirmation HTML page with a submit button. Does NOT mutate state — the form POSTs the verified token back to this endpoint to trigger the actual unsubscription. Link prefetchers and crawlers that follow the link will see only the confirmation page and cannot unsubscribe the recipient.

Public Public: no authentication

Parameters

Responses

One-click unsubscribe (public)

RFC 8058 one-click `List-Unsubscribe-Post` endpoint and confirmation form submission handler. Verifies the HMAC-signed token (via `?token=` query param, `application/x-www-form-urlencoded` body field, or JSON `token` field), then sets the marketing objection flag on the email address and adds it to the suppression list. Returns `{ unsubscribed: true, email: "..." }` on success. Per-IP rate-limited before any HMAC or database work.

Public Public: no authentication

Parameters

Request Body

Responses

Set auto-dispatch for a category

Enables or disables automatic dispatch for a helpdesk category. ELEVATED: requires MFA step-up (human path); SP enforces elevated grant floor for API-key path.

Auth Session JWT (Bearer)

Request Body

Responses

Create or update a helpdesk dispatch category

Creates or updates a helpdesk category configuration entry, including inheritance columns, auto-dispatch settings, and dispatch-policy overrides. SP self-gates on `support.config` / `org.update`.

Auth Session JWT (Bearer)

Request Body

Responses

Delete a helpdesk category

Deletes a helpdesk category row by ID. SP self-gates on `support.config`.

Auth Session JWT (Bearer)

Parameters

Responses

List effective helpdesk categories

Returns the merged effective category set for a given `saas_package_id` and/or `project_id` tuple. This is the single source of truth for the ticket editor. SP self-gates on `support.read`.

Auth Session JWT (Bearer)

Parameters

Responses

List VW-to-category assignments

Returns virtual worker assignments for helpdesk categories. Supports optional `category_key`, `saas_package_id`, and `project_id` filters.

Auth Session JWT (Bearer)

Parameters

Responses

Assign a virtual worker to a helpdesk category

Associates a virtual worker with a helpdesk dispatch category. Optionally scoped to a SaaS package or project. The virtual worker must be accessible to the caller (cross-org reject enforced at SP).

Auth Session JWT (Bearer)

Request Body

Responses

Remove a VW-to-category assignment

Removes a virtual worker assignment by assignment ID. SP self-gates on `support.config`.

Auth Session JWT (Bearer)

Parameters

Responses

Set container pool policy

Configures the container pool limits and timing policy for the organization's helpdesk workers. Requires MFA step-up.

Auth Session JWT (Bearer)

Request Body

Responses

Get container pool policy

Returns the organization's container pool policy (max slots, idle grace period, pool floor, etc.). Read-only; no MFA step-up required.

Auth Session JWT (Bearer)

Responses

Get live container pool status

Returns live per-virtual-worker container and slot occupancy. Optionally filtered by `virtual_worker_id`. SP self-gates on `support.read`.

Auth Session JWT (Bearer)

Parameters

Responses

Get container slot configuration

Returns the per-worker container slot count configuration.

Auth Session JWT (Bearer)

Responses

Set container slot count for a worker

Configures the maximum number of concurrent container slots for a virtual worker (1–16). Requires MFA step-up.

Auth Session JWT (Bearer)

Request Body

Responses

Get Cloudflare OAuth authorization URL

Returns the Cloudflare OAuth (PKCE) authorization URL. Accepts an optional `?purpose=` parameter (`dns` or `worker_sync`) to tailor the requested scopes. Feature-flag gated.

Auth Session JWT (Bearer)

Parameters

Responses

Connect Cloudflare via authorization code

Completes the Cloudflare PKCE OAuth flow. Validates the CSRF `state` JWT, exchanges `code` for tokens, and stores the encrypted credential. Applies a scope-allowlist to prevent scope-confusion attacks. Feature-flag gated.

Auth Session JWT (Bearer)

Request Body

Responses

Disconnect Cloudflare integration

Revokes and removes the stored Cloudflare OAuth credential for the caller's organization.

Auth Session JWT (Bearer)

Responses

Get GitHub OAuth authorization URL

Returns the GitHub OAuth authorization URL the client should redirect the user to. The `state` is a signed CSRF JWT (HS256, 10-minute expiry) that must be round-tripped back to `/v1/integrations/github/callback`. Feature-flag gated; returns 503 when the GitHub OAuth application is not configured.

Auth Session JWT (Bearer)

Responses

Handle GitHub OAuth callback

Completes the GitHub OAuth flow. Exchanges `code` for an access token, stores the encrypted credential, and returns the connection record. `state` is validated against the signed CSRF JWT issued by the authorize endpoint. Feature-flag gated.

Auth Session JWT (Bearer)

Parameters

Responses

Connect GitHub via authorization code

Exchanges a GitHub OAuth authorization code for a stored connection. Validates the `state` CSRF JWT, stores the encrypted OAuth token, and links the connection to the caller's organization. Feature-flag gated.

Auth Session JWT (Bearer)

Request Body

Responses

Disconnect GitHub integration

Revokes the stored GitHub OAuth credential and removes the connection record for the caller's organization.

Auth Session JWT (Bearer)

Responses