---
title: "Acquire a short exclusive lock on the mailbox's `.mv2` memory file"
method: POST
path: "/v1/mailboxes/{mailbox_id}/memory/lock"
tags: ["memory"]
---

# Acquire a short exclusive lock on the mailbox's \`.mv2\` memory file

`POST /v1/mailboxes/{mailbox_id}/memory/lock`

## Request

- Base URL: `https://mbag.ai/api`
- URL: `https://mbag.ai/api/v1/mailboxes/{mailbox_id}/memory/lock`
- Auth: HTTP bearer

Fixed 30-second lock duration. Before any file has ever been
uploaded there is nothing to lock yet, so the first acquire always
succeeds (races between two first-writers are an accepted edge —
every subsequent write is properly serialised).

## Path parameters

- `mailbox_id` integer, required

## Response `200`

Lock acquired. Empty body.

## Other responses

- `401`: Missing or invalid credential, raised by the `ApiKeyAuth` extractor (`backend/src/api_keys.rs`) before the handler runs: no `Authorization` header, a non-`Bearer` scheme, a key that doesn't hash-match any row, or a key whose status isn't `active`. A header that isn't valid UTF-8, has no scheme token, or has `Bearer` with no key value returns 400 with this same JSON shape instead of 401.
- `404`: Mailbox not found (or not owned by the caller). Plain-text body.
- `409`: Memory file is currently locked by another writer. Plain-text body.
- `500`: Database error checking mailbox ownership or acquiring the lock. Plain-text body.

---

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