Create an app password
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.
BetterAuth session cookie. Used by the dashboard / browser clients. When present, the active project is taken from the x-project-id header.
In: cookie
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Body for POST /api/mailboxes/:id/app-passwords.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/mailboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/app-passwords" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{
"success": true,
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"revealUrl": "http://example.com",
"revealExpiresAt": "2019-08-24T14:15:22Z"
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}{
"success": false,
"error": {
"message": "string",
"code": "string",
"details": {
"errors": [
null
]
}
}
}