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

# Create a mailbox app password

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

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/mailboxes/{id}/app-passwords`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

Create a revocable IMAP, SMTP, and JMAP credential. A mailbox can have at most five active app passwords. The secret is returned once in the 201 response and is never stored by Shipmail. Expiration defaults to 90 days and cannot exceed one year. Idempotency-Key is rejected because replaying a cached plaintext secret would violate the one-time-secret guarantee.

## Headers

- `X-Shipmail-Organization` string

## Request body

- CreateMailboxAppPasswordRequest
  - `name` string, required
  - `expires_at` string, date-time: Optional expiry. Defaults to 90 days and cannot exceed one year.
  - `allowed_cidrs` string[]

## Response `201`

App password created. Save the secret now.

- CreatedMailboxAppPassword
  - `object` 'mailbox_app_password', required
  - `id` string, required
  - `mailbox_id` string, required
  - `name` string, required
  - `state` 'pending_create' | 'active' | 'pending_revoke' | 'revoked' | 'failed', required
  - `purpose` 'operator_client', required
  - `expires_at` string, date-time, nullable, required
  - `allowed_cidrs` string[], required
  - `last_used_at` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `revoked_at` string, date-time, nullable, required
  - `secret` string, required: One-time plaintext secret. Shipmail does not store or return it again.

## Other responses

- `403`: Insufficient permissions.
- `404`: Resource not found.
- `409`: Resource conflict.
- `422`: Validation failed.
- `429`: Rate limit exceeded.

---

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