---
title: "Account API"
description: "Account in the OneSend API: 15 endpoints. Your own account: profile, password, email address, two-factor authentication and sessions. Session only."
url: https://onesend.email/docs/api-reference/account/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Account

Your own account: profile, password, email address, two-factor authentication and sessions. Session only.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## Your account

GET `/v1/account`

Profile, two-factor status and a pending email change. Session only.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "id": string,
  "email": string,
  "name": string or null,
  "createdAt": string,
  "passwordChangedAt": string or null,
  "twoFactor": {
    "enabled": boolean,
    "enabledAt": string or null,
    "recoveryCodesRemaining": number
  },
  "pendingEmail": string or null
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Update your profile

PATCH `/v1/account`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name`required | `string or null` |  |

### Responses

`200` Success

```
{
  "id": string,
  "email": string,
  "name": string or null,
  "createdAt": string,
  "passwordChangedAt": string or null,
  "twoFactor": {
    "enabled": boolean,
    "enabledAt": string or null,
    "recoveryCodesRemaining": number
  },
  "pendingEmail": string or null
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Delete your account

DELETE `/v1/account`

Session only. Confirm with your password (and a two-factor code if it is on). Not possible while you own a workspace: transfer ownership or delete the workspace first (409 `owns_workspaces`). Removes your account, memberships, sessions and app passwords; workspace data you created stays with the workspace. As when you leave a workspace, the API keys you created are revoked, and the inbox rules, mailbox forwarding and webhooks you set up that send mail out of a workspace are turned off.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `password`required | `string` | Your current password |
| `code` | `string` | Two-factor code or recovery code, when two-factor authentication is on for your account |

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Change your password

POST `/v1/account/password`

Needs the current password. Signs out every other session; this one stays signed in.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `currentPassword`required | `string` |  |
| `newPassword`required | `string` |  |

### Responses

`200` Success

```
{
  "ok": true,
  "sessionsRevoked": number
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Change your email address

POST `/v1/account/email`

Needs the current password. Sends a confirmation link (24 hours) to the new address; the address changes when it is opened.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `email`required | `string (email)` |  |
| `password`required | `string` |  |

### Responses

`202` Success

```
{
  "ok": true,
  "message": string,
  "emailDelivery": boolean
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Confirm an email change

POST `/v1/auth/email/confirm`

Opens the link sent to the new address. The token is single use. The previous address gets a notice.

**Authentication:** None.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `token`required | `string` |  |

### Responses

`200` Success

```
{
  "ok": true,
  "email": string
}
```

**Errors: 400, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Verify your email address

POST `/v1/account/email-verification`

Sends a link (24 hours) to your account's address; opening it marks the address as verified. Session only. Operator addresses (ONESEND\_ADMIN\_EMAILS) cannot be verified this way (403 `cli_verification_required`): instance admins need a verified address, and the link would travel through a workspace's own sending providers. Run `onesend-admin verify-email <email>` on the server instead.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`202` Success

```
{
  "ok": true,
  "message": string,
  "emailDelivery": boolean,
  "verified": boolean
}
```

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## List your active sessions

GET `/v1/account/sessions`

Device (from the User-Agent), a keyed hash of the IP address, and when each was last used.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "device": string,
    "userAgent": string or null,
    "ipHash": string or null,
    "createdAt": string,
    "lastSeenAt": string,
    "expiresAt": string,
    "current": boolean,
    "twoFactor": boolean
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Revoke a session

DELETE `/v1/account/sessions/{id}`

Signs that device out at once.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Sign out everywhere else

POST `/v1/account/sessions/revoke-others`

Revokes every session except this one.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "revoked": number
}
```

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Start two-factor setup

POST `/v1/account/2fa/setup`

Needs the current password. Returns a new TOTP secret (RFC 6238, 6 digits, 30 seconds) to add to an authenticator app. Two-factor is on after POST /v1/account/2fa/enable with a code.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `password`required | `string` |  |

### Responses

`200` Success

```
{
  "secret": string,
  "otpauthUrl": string,
  "issuer": string,
  "account": string
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Turn on two-factor authentication

POST `/v1/account/2fa/enable`

Send a current code from the authenticator app. Returns 10 recovery codes, shown only once; each works one time instead of a code. This session counts as signed in with two-factor.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `code`required | `string` |  |

### Responses

`200` Success

```
{
  "recoveryCodes": [string]
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Turn off two-factor authentication

POST `/v1/account/2fa/disable`

Needs the current password and a code (or a recovery code). Workspaces that require two-factor stay locked for you until you turn it on again.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `password`required | `string` |  |
| `code`required | `string` | A current code, or a recovery code |

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## New recovery codes

POST `/v1/account/2fa/recovery-codes`

Needs the current password and a code. The previous recovery codes stop working.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `password`required | `string` |  |
| `code`required | `string` | A current code, or a recovery code |

### Responses

`200` Success

```
{
  "recoveryCodes": [string]
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Delete an account without a workspace

POST `/v1/auth/delete-account`

For accounts that can no longer sign in because they have no workspace left (for example after the workspace was deleted). Same checks as DELETE /v1/account: password, a two-factor code if it is on, and no owned workspaces.

**Authentication:** None.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `password`required | `string` | Your current password |
| `code` | `string` | Two-factor code or recovery code, when two-factor authentication is on for your account |
| `email`required | `string (email)` |  |

### Responses

`204` No content

**Errors: 400, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
