Skip to main content

Mailboxes

Endpoints: /v1/workspaces/:workspaceId/mailboxes (and .../mailboxes/:mailboxId/...). Auth: Bearer + x-workspace-id.

GET /v1/workspaces/:workspaceId/mailboxes​

List mailboxes in the workspace.

Response (200): Array of mailbox objects (id, provider, connection status, etc.).

Example:

curl -X GET https://api.inboxops.app/v1/workspaces/ws-123/mailboxes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: ws-123"

POST /v1/workspaces/:workspaceId/mailboxes​

Create (register) a mailbox. Typically used before starting the OAuth connect flow. Body may include provider type and optional config.

Body: Provider-specific (e.g. provider type). Exact schema depends on the product.

Response (201): Created mailbox (e.g. id, provider). Use the returned id for connect/sync/health.

Example:

curl -X POST https://api.inboxops.app/v1/workspaces/ws-123/mailboxes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: ws-123" \
  -H "Content-Type: application/json" \
  -d '{"provider":"microsoft"}'

GET /v1/workspaces/:workspaceId/mailboxes/:mailboxId​

Get one mailbox.

Response (200): Mailbox object.

Example:

curl -X GET https://api.inboxops.app/v1/workspaces/ws-123/mailboxes/MAILBOX_UUID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: ws-123"

POST /v1/workspaces/:workspaceId/mailboxes/:mailboxId/connect​

Start or complete the OAuth connection flow for the mailbox. The API may return a URL for the user to visit or accept callback params. Behavior is provider-specific.

Body (if any): Callback or token data as required by the product.

Response (200): Connection result or redirect URL.

POST /v1/workspaces/:workspaceId/mailboxes/:mailboxId/disconnect​

Disconnect the mailbox (revoke OAuth). The mailbox will no longer receive new mail until reconnected.

Response (200): Success.

Example:

curl -X POST https://api.inboxops.app/v1/workspaces/ws-123/mailboxes/MAILBOX_UUID/disconnect \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: ws-123"

POST /v1/workspaces/:workspaceId/mailboxes/:mailboxId/sync​

Trigger a manual sync for the mailbox.

Response (200): Accepted or sync status.

Example:

curl -X POST https://api.inboxops.app/v1/workspaces/ws-123/mailboxes/MAILBOX_UUID/sync \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: ws-123"

GET /v1/workspaces/:workspaceId/mailboxes/:mailboxId/health​

Get mailbox health (connection status, last sync, errors). Admin or operational use.

Response (200): Health object.

Example:

curl -X GET https://api.inboxops.app/v1/workspaces/ws-123/mailboxes/MAILBOX_UUID/health \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-workspace-id: ws-123"