---
title: "Check and store a mailbox password"
method: PUT
path: "/api/v1/mail/mailboxes/{id}/password"
tags: ["Desk"]
---

# Check and store a mailbox password

`PUT /api/v1/mail/mailboxes/{id}/password`

## Request

- Base URL: `http://localhost:5180`
- URL: `http://localhost:5180/api/v1/mail/mailboxes/{id}/password`
- Auth: API key in cookie `better-auth.session_token`

Signs in to the mailbox IMAP server, and to its SMTP server where it names one, with the password given. Only when every server lets it in is the password stored, sealed under a key only the mail service can open: no endpoint ever returns it, and this account cannot read it back. The mailbox then moves to `connecting` until the mail service has read it.

## Path parameters

- `id` string, required

## Request body

- object
  - `password` string, required: Checked against the mailbox servers, then stored sealed. It is never returned by any endpoint.
  - `username` string: Who to sign in as, where it is not the address. Saved on the mailbox.

## Response `200`

The servers accepted it and it is stored.

- object
  - `ok` unknown, required
  - `data` object, required
    - `mailboxId` string, required: Stable record id, e.g. `lse_012`.
    - `status` string, required: The mailbox status now: `connecting` until the mail service has read it once.
    - `passwordVerifiedAt` string, required: ISO 8601 timestamp.
    - `imap` 'ok' | 'refused' | 'unreachable', required
    - `smtp` 'ok' | 'refused' | 'unreachable' | 'skipped', required
  - `meta` object, required
    - `requestId` string, required: Echoed in the x-request-id header. Quote it in a bug report.

## Other responses

- `404`: No such mailbox on this team.
- `409`: The mailbox changed while this was saved. Read it again and retry.
- `422`: A server refused the login or could not be reached, so nothing was stored: `details.imap` and `details.smtp` say which. Or the mailbox does not sign in with a password, or this deployment cannot store one (`details.reason`).

---

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