SBX API

The SBX API lets you script shared mailbox provisioning and membership changes instead of doing them in the SBX portal. It is a REST API with JSON request and response bodies.

Base URL: https://api.sbx.tools/api/v1

An interactive reference with every endpoint and schema is at api.sbx.tools/api/docs.

Authentication

Requests are authenticated with an API key sent in the X-Api-Key header.

1. In the SBX portal, open Company settings and then API keys.
2. Click Create API key, give it a name, and optionally set an expiry date.
3. Copy the key. It is shown only once.

Only SBX administrators can create keys. A key acts with the rights of the administrator who created it and stops working if that administrator is removed or loses administrator access. You can have up to 10 active keys and revoke any of them at any time from the same page.

curl https://api.sbx.tools/api/v1/shared-mailboxes \
  -H "X-Api-Key: sbx_your_key_here"

Each key may make 60 requests per minute. Requests above that limit get 429 Too Many Requests.

Identifiers

Shared mailboxes and users are both referenced by their Entra object ID. This is the id Microsoft Graph returns for a user, and the "Object ID" shown on a user's page in the Entra admin center. A shared mailbox is a user object in Entra, so one kind of identifier covers both.

With Microsoft Graph PowerShell:

(Get-MgUser -Filter "mail eq 'support@contoso.com'").Id

Endpoints

Register a shared mailbox

POST /shared-mailboxes

{
  "id": "6b2f1c9e-0d3a-4e7b-9f1a-2c3d4e5f6a7b",
  "name": "support",
  "displayName": "Support",
  "memberIds": [
    "1a2b3c4d-1111-2222-3333-444455556666",
    "9f8e7d6c-aaaa-bbbb-cccc-ddddeeeeffff"
  ],
  "removeConversationFromInboxOnAssignment": false,
  "removeConversationFromInboxOnClose": false,
  "removeAssigneeAfterClosing": false
}

• id is required. The mailbox must exist in your Microsoft 365 tenant.
• name is optional. It is the short name SBX uses, for example in Outlook category names: 1 to 15 lowercase letters or digits, unique within your company. When omitted it is derived from the mailbox address.
• displayName is optional and defaults to the name in your directory.
• memberIds may be empty. Every member must exist in your tenant and have an email address.
• The three boolean settings default to false and match the options shown when creating a shared mailbox in the portal.

Returns 201 Created with the mailbox:

{
  "id": "6b2f1c9e-0d3a-4e7b-9f1a-2c3d4e5f6a7b",
  "name": "support",
  "displayName": "Support",
  "mail": "support@contoso.com",
  "members": [
    { "id": "1a2b3c4d-1111-2222-3333-444455556666", "name": "anna", "displayName": "Anna Example", "mail": "anna@contoso.com" }
  ]
}

Nothing is created if any ID cannot be resolved, so a failed request leaves SBX unchanged.

Add a member

PUT /shared-mailboxes/{id}/members/{userId}

No request body. Returns 200 OK with the member. Adding a user who is already a member is a no-op and also returns 200, so the call is safe to repeat.

curl -X PUT https://api.sbx.tools/api/v1/shared-mailboxes/6b2f1c9e-0d3a-4e7b-9f1a-2c3d4e5f6a7b/members/1a2b3c4d-1111-2222-3333-444455556666 \
  -H "X-Api-Key: sbx_your_key_here"

Remove a member

DELETE /shared-mailboxes/{id}/members/{userId}

Optional query parameter reassignTo: the Entra object ID of a remaining member who takes over the removed user's open conversations. Without it, those conversations become unassigned. Returns 204 No Content.

curl -X DELETE "https://api.sbx.tools/api/v1/shared-mailboxes/6b2f1c9e-0d3a-4e7b-9f1a-2c3d4e5f6a7b/members/1a2b3c4d-1111-2222-3333-444455556666?reassignTo=9f8e7d6c-aaaa-bbbb-cccc-ddddeeeeffff" \
  -H "X-Api-Key: sbx_your_key_here"

Errors

Errors use the standard application/problem+json format with an extra code field you can branch on. The one exception is a request body that cannot be parsed, for example malformed JSON or a string where an array is expected: that returns ASP.NET's standard validation response with an errors object and no code. Sending both an X-Api-Key and an Authorization header is rejected with 400 and code mixed_credentials.

{
  "status": 409,
  "title": "Conflict",
  "detail": "Shared mailbox 6b2f1c9e-... is already registered in SBX as 'support'.",
  "code": "already_registered"
}

PowerShell example

$headers = @{ 'X-Api-Key' = $env:SBX_API_KEY }
$base = 'https://api.sbx.tools/api/v1'

# Register a shared mailbox with two members
$body = @{
  id        = (Get-MgUser -Filter "mail eq 'support@contoso.com'").Id
  memberIds = @(
    (Get-MgUser -Filter "mail eq 'anna@contoso.com'").Id,
    (Get-MgUser -Filter "mail eq 'ben@contoso.com'").Id
  )
} | ConvertTo-Json

$mailbox = Invoke-RestMethod -Method Post -Uri "$base/shared-mailboxes" -Headers $headers -ContentType 'application/json' -Body $body

# Offboard a user and hand their open conversations to Anna
$leaver = (Get-MgUser -Filter "mail eq 'ben@contoso.com'").Id
$anna   = (Get-MgUser -Filter "mail eq 'anna@contoso.com'").Id
Invoke-RestMethod -Method Delete -Uri "$base/shared-mailboxes/$($mailbox.id)/members/${leaver}?reassignTo=$anna" -Headers $headers