---
title: "Create an app password"
method: POST
path: "/api/mailboxes/{id}/app-passwords"
tags: ["Mailboxes"]
---

# Create an app password

`POST /api/mailboxes/{id}/app-passwords`

## Request

- Base URL: `https://api.sendly.now`
- URL: `https://api.sendly.now/api/mailboxes/{id}/app-passwords`
- Auth: one of:
  - API key in cookie `better-auth.session_token`
  - OAuth 2 (authorization code, authorization URL `https://app.sendly.now/api/auth/oauth2/authorize`, token URL `https://app.sendly.now/api/auth/oauth2/token`, scopes: `mailboxes:write`)

Mint an IMAP/SMTP credential for the mailbox, so a mail client can connect to it.

**The secret is not in the response.** A delegated caller receives `revealUrl` — a single-use link that shows the password once in a browser, to a signed-in project admin. The connection that created the password cannot open its own link, and the link is spent by the first attempt to open it, successful or not.

That is deliberate and not a limitation to work around: an app password is a live mail credential that a client authenticates with directly, it outlives the grant that created it, and it is revoked from a different screen. Returning it inline would place a working mail credential in an agent's context, its transcript, and every log that transcript reaches.

Requires an admin of the project. An API key is refused with 401 — this endpoint needs a user, so use an OAuth connection.

Requires the `mailboxes:write` scope — Create and delete mailboxes on your verified domains.

## Path parameters

- `id` string, uuid, required

## Request body

- CreateAppPassword: Body for POST /api/mailboxes/:id/app-passwords.
  - `name` string, required
  - `scopes` string[]

## Response `201`

App password created; the secret is behind the one-time link

- object
  - `data` AppPasswordReveal, required: A newly created app password, handed over as a one-time link rather than as a secret.
    - `id` string, uuid, required
    - `revealExpiresAt` string, date-time, required: When the link stops working. Five minutes after creation; the password itself does not expire.
    - `revealUrl` string, uri, required: A single-use link that shows the password once, in a browser. Opening it requires a signed-in Sendly session belonging to a project admin — the connection that created the password cannot open it, and the second attempt to open it fails whoever makes it.
  - `success` true, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized — missing or invalid auth
- `403`: Forbidden — insufficient permissions or project disabled
- `404`: Resource not found
- `429`: Rate limit or billing limit exceeded
- `500`: Internal server error

---

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