Exchange is excluded from this API/CLI release. Any historical Exchange API or CLI example in this guide is unavailable; native portal behavior is outside this exclusion. See [current release scope](/developers/guides/release-scope?lang=en). # Shared mailboxes: portal, API and CLI Manage addresses such as `info@voorbeeld.nl` or `verkoop@voorbeeld.nl` as a separate mailbox accessible to existing colleagues. The shared mailbox has a **paid normal mail package with its own quota**. It has no personal login, password, settings PDF, Drive or Conserio. A single **Access** choice grants full mailbox rights and sending as the shared address. Members see the mailbox in webmail and their mail client. Incoming mail stays in that mailbox rather than being delivered as a copy to each member. Separate Send As permissions, read-only members, Send on Behalf, folder sharing and mailing lists are outside this feature. Access to a **personal** mailbox, separate Send As, calendars, mailing lists and rooms uses the [separate free collaboration feature](/developers/guides/workspace-mail-collaboration?lang=en). Shared mailbox group memberships remain separate. ## Using the portal 1. Open the correct **Workspace** and go to **Shared mailboxes**. The overview shows the address, members, measured usage/quota and status. You need current management rights for this company; read-only access provides no edit buttons. 2. Choose **Add shared mailbox**. Select an active mail domain, enter the name before `@` and an optional display name, and choose a normal mail package. The form shows the quota and monthly price excluding VAT. 3. Enter optional **Extra email addresses**, one full address per line, and select existing colleagues under **Members**. Domains and colleagues must belong to the same company and mail server. An address already used by a mailbox or alias cannot be reused. 4. Review the package and costs, tick the cost confirmation and choose **Order shared mailbox**. Existing strong verification may first request your passkey or an allowed second factor. An old tab or changed product requires a new review. 5. For prepayment, use the displayed payment action. **Being configured** means the request is running in the background; it is not yet a confirmed mailbox. Status refreshes automatically. Wait until the mailbox is active before making further changes. For **Synchronization requires inspection**, support inspects the original request: do not order the same mailbox again. Click the shared address to change its name and extra addresses. The submitted alias list replaces its entire own list. Under **Members**, grant or remove a colleague's access. The same relationship appears on an ordinary mailbox under **Access to shared mailboxes**. A change concerns only the selected shared mailbox; that colleague's other memberships remain intact. A blocked ordinary mailbox remains a member but cannot log in. Under **Mail package and usage**, view the selected package and most recently measured usage. In this first version, package changes are not offered through the shared mailbox form or `PATCH`. **Delete shared mailbox** permanently removes stored mail. Read the warning, type the full address and confirm deletion with recent strong verification. The worker first removes the memberships, verifies their removal and then destroys the mailbox. The request stays visible while the supplier has not confirmed the outcome. Ordinary mailboxes and their other shared access remain intact. ## Payment and storage The normal mail package determines price and individual quota. One `shared_mailbox` line appears on the same company monthly invoice, without a second workplace line, extra storage pool or new separate legacy WeFact subscription. Storage counts once toward company mail usage. Existing payment settings determine monthly invoicing or online payment of the prorated first period; for prepayment, delivery starts only after confirmed payment of the correct invoice. An API request has the same cost controls as a portal order. Deletion creates no new order, invoice or refund. Historical lines and paid periods are retained. Moving a workspace to another company and permanently purging it remain blocked while shared mailboxes, related memberships or alias addresses would cross the company boundary. Remove them first through the explicit shared mailbox workflow. ## API contract and permissions All paths below start with `/api/v1/accounts/{account}/workspaces/{workspace}`. | Method and path | Purpose | | --- | --- | | `GET /shared-mailboxes` | Overview; `limit` 1–100 and opaque `cursor` | | `POST /shared-mailboxes` | Paid creation with a reviewed product | | `GET /shared-mailboxes/{shared}` | Detail, `version` and `ETag` | | `PATCH /shared-mailboxes/{shared}` | Change only the name and/or complete alias list | | `DELETE /shared-mailboxes/{shared}` | Permanent deletion with typed `confirm_address` | | `GET /shared-mailboxes/{shared}/members` | Visible colleagues with access | | `PUT /shared-mailboxes/{shared}/members/{mailbox}` | Grant access to one colleague | | `DELETE /shared-mailboxes/{shared}/members/{mailbox}` | Remove one access relationship | | `GET /mailboxes/{mailbox}/shared-mailboxes` | View the same access from the colleague's side | Reading requires `workspace.mailboxes:read`; changing requires `workspace.mailboxes:write`. Creation additionally requires `orders:commit`, current ordering permissions and a service connection's existing order and monthly limits. Prior catalog and workspace checks require `products:read` and `workspace:read`, respectively. `operations:read` allows following the returned operation. A mailbox ID is not authorization: the server checks current company binding, role and workspace resource restrictions. A member from another company receives `404`. Changing access for colleagues from another workspace of the same company on the same mail server also requires write permissions on that workspace. Read results contain only colleagues within your permitted read scope. An alias on another Workspace domain also requires write permissions on that workspace. A restricted token sees no hidden members, aliases or shared mailboxes outside its allowed workspaces. Such a connection can change the shared mailbox only if it may also manage every already involved workspace; this is checked before saving. Every write uses `Idempotency-Key`. For creation, use `If-Match` with the current **workspace ETag**; for updates and membership changes, use the current **shared mailbox ETag**. Read the new version after each change. Creation requires the exact product ETag as `product_version`; an expired price review gives `412`. `X-Binadit-Dry-Run: true` or `dry_run: true` validates and shows the plan without a reservation, order, queued task or supplier write. Deletion additionally requires a real personal connection with recent strong verification and the server flag allowing sensitive actions. A service token cannot replace this human confirmation. The typed confirmation is the full email address, not a mailbox ID. ## Creating with curl and the CLI First read the normal mailbox product and workspace. Review price and quota and replace all example IDs and versions. Save the exact body, for example as `shared.json`: ```json {"domain_id":12,"local_part":"info","display_name":"Informatie","product_id":8,"product_version":"","aliases":["verkoop@voorbeeld.nl"],"member_ids":[23,24]} ``` A curl example with a privately loaded token; do not put real tokens in chat, shared files or shell history: ```sh curl --fail-with-body "$BINADIT_ENDPOINT/api/v1/accounts/42/workspaces/7/shared-mailboxes" \ -H "Authorization: Bearer $BINADIT_ACCESS_TOKEN" -H 'Content-Type: application/json' \ -H 'If-Match: ""' -H 'Idempotency-Key: shared-info-reviewed-20261031' \ --data-binary @shared.json ``` The typed CLI uses the same routes and preserves the original request intent: ```sh binadit workspace shared-mailboxes list 7 --account 42 binadit workspace shared-mailboxes create 7 --account 42 --version '' --input shared.json --dry-run binadit workspace shared-mailboxes create 7 --account 42 --version '' --input shared.json --yes binadit workspace shared-mailboxes get 7 31 --account 42 binadit workspace shared-mailboxes members list 7 31 --account 42 binadit workspace shared-mailboxes members add 7 31 23 --account 42 --version '' --yes binadit workspace shared-mailboxes members remove 7 31 24 --account 42 --version '' --yes binadit workspace shared-mailboxes access 7 23 --account 42 ``` For the name/aliases, use `update WORKSPACE SHARED --input FILE --version ETAG --yes`. For example, `{"display_name":"Informatie en verkoop","aliases":["verkoop@voorbeeld.nl"]}`. The array replaces all its own aliases; supply `[]` to remove them. `product_id`, quotas, passwords, Drive and Conserio are not allowed update fields. For permanent deletion: ```sh binadit workspace shared-mailboxes delete 7 31 --account 42 --version '' \ --confirm-address 'info@voorbeeld.nl' --yes ``` ## Progress and an unclear response The response contains `task_ids` and `delivery_status`. `queued` means accepted background processing; `awaiting_payment` means waiting for payment. Follow the original operation with `binadit operations watch OPERATION_UUID --account 42`, then read the mailbox detail. An accepted HTTP call does not prove that the mailbox or access has been confirmed on the mail server. After a timeout, preserve the first operation, key and exact input. Do not create a new creation intent to bypass an unknown result. The worker first looks up the original `externalId`, retains received acknowledgements and repeats no uncertain creation or destruction. Known payment does not authorize using another account or new supplier. After permissions are revoked or the company/source changes, further work remains blocked until the original situation has been explicitly reviewed. For agents: discover current contracts through [OpenAPI](/developers/openapi.json) and your connection's abilities through `capabilities`. Use only the scopes above and existing IDs. Do not implement a personal login for a shared mailbox or fabricate an actor or new recovery intent. See also the [agent manual](/developers/agents?lang=en) and [Workspace billing boundaries](/developers/guides/workspace-billing?lang=en).