---
title: "Update a mailbox grant"
method: PATCH
path: "/v1/mailboxes/{id}/grants/{grantId}"
tags: ["Mailboxes"]
---

# Update a mailbox grant

`PATCH /v1/mailboxes/{id}/grants/{grantId}`

## Request

- Base URL: `https://api.samva.dev`
- URL: `https://api.samva.dev/v1/mailboxes/{id}/grants/{grantId}`
- Auth: API key in header `x-api-key`

Changes a member's role, send mode, or both on a mailbox and returns the updated grant. A field left out keeps its value; naming neither is a validation error. Taking admin from the last grant that can configure the mailbox conflicts, as revoking it does. The change applies to the member's next request on every surface.

## Path parameters

- `id` string, required
- `grantId` string, required

## Request body

- UpdateMailboxGrantPayload
  - `role` 'admin' | 'collaborator' | 'viewer'
  - `sendMode` 'send' | 'approval': How the grantee's sends execute: `send` runs them within account limits; `approval` holds each one until a different member approves it.

## Response `200`

MailboxGrant

- MailboxGrant
  - `id` string, required
  - `actor` object, required
    - `kind` 'user' | 'apiKey' | 'extension' | 'externalAgent' | 'samvaAgent' | 'system', required
    - `id` string, required
    - `displayName` string, nullable
  - `permissions` string[], required
  - `sendMode` 'send' | 'approval', required: How the grantee's sends execute: `send` runs them within account limits; `approval` holds each one until a different member approves it.
  - `createdAt` string, required

## Other responses

- `401`: UnauthorizedError
- `403`: ForbiddenError
- `404`: ResourceNotFoundError
- `409`: ConflictError
- `422`: ValidationError
- `500`: InternalError
- `504`: GatewayTimeoutError

---

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