---
title: "Replace a mailbox's access"
method: PUT
path: "/mailboxes/{address}/access"
tags: ["Mailbox access"]
---

# Replace a mailbox's access

`PUT /mailboxes/{address}/access`

## Request

- Base URL: `https://api.primitive.dev/v1`
- URL: `https://api.primitive.dev/v1/mailboxes/{address}/access`
- Auth: HTTP bearer

Replaces the whole access list of one mailbox address, or of a domain (`@example.com` or the bare domain). Needs delegations:manage: a dashboard session, the person's own Primitive CLI, or an org-wide API key, which acts for the person it belongs to and works only while that person is still an owner or admin holding the permission. Any other OAuth app answers `step_up_required` until the person confirms in the dashboard and the request carries the Primitive-Step-Up header. Narrowed, Function and connected keys are refused. Nobody grants access beyond their own (rule 1): each added or widened entry must be within the caller's own mail access and permissions; an API key never gives access to a member's personal mailbox. Every change is recorded in the credential audit log.

## Path parameters

- `address` string, required

## Request body

- SetMailboxAccessRequest
  - `entries` object[], required
    - `principal` object, required
      - `kind` 'member' | 'group' | 'agent' | 'address', required
      - `id` string, required
    - `actions` string[], required
    - `depth` 'metadata' | 'content' | 'raw'

## Response `200`

Replace a mailbox's access

- object
  - `success` true, required
  - `data` SetMailboxAccessResult, required
    - `entries` object[], required
      - `id` string, required
      - `mailbox_address` string, nullable, required
      - `mailbox_domain` string, nullable, required
      - `mailbox_kind` 'personal' | 'shared' | 'agent' | 'app', nullable, required
      - `principal_kind` 'member' | 'group' | 'agent' | 'app' | 'address', required
      - `principal_user_id` string, nullable, required
      - `principal_group_id` string, nullable, required
      - `principal_agent_connection_id` string, nullable, required
      - `principal_address` string, nullable, required
      - `actions` string[], required
      - `depth` 'metadata' | 'content' | 'raw', required
      - `created_at` string, required
      - `updated_at` string, required

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `403`: Authenticated caller lacks permission for the operation
- `404`: feature_disabled: the feature is not enabled for the organization; or not_found: the item the path names does not exist.
- `409`: conflict: the item changed while you edited it, or a member was removed and added back. Look again, then retry.
- `429`: Rate limit exceeded. The `ratelimit-*` headers describe the limiter that rejected this request, with its own limit and window, not the API budget that successful responses report. A limiter that reports only a wait sends `Retry-After` alone.

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) - [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) - [OpenAPI document](https://skmtc.dev/primitive/apis/primitive-api/revisions/bce409c97acb?raw)