# Panel settings

URL: https://docs.vaultpanel.net/api-reference/settings

> API reference for the panel's own settings - putting the panel on a domain, its address, and the email it sends for invites, password resets and alerts.

`/settings` holds the settings of the panel itself: the domain it is served on and the email it sends. Everything here needs `settings.manage` (owners and admins); with an API token, only the `full` scope grants it. Other panel-wide settings live with their feature: [panel access, the two-factor policy and sessions](https://docs.vaultpanel.net/api-reference/security), [backup storage](https://docs.vaultpanel.net/api-reference/backups) and [the AI assistant](https://docs.vaultpanel.net/api-reference/assistant).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/settings/panel-domain` | [Get the panel domain](https://docs.vaultpanel.net/api-reference/settings#get-the-panel-domain) |
| PUT | `/api/v1/settings/panel-domain` | [Put the panel on a domain](https://docs.vaultpanel.net/api-reference/settings#put-the-panel-on-a-domain) |
| PUT | `/api/v1/settings/panel-domain/address` | [Use the domain as the panel's address](https://docs.vaultpanel.net/api-reference/settings#use-the-domain-as-the-panels-address) |
| DELETE | `/api/v1/settings/panel-domain` | [Take the panel off its domain](https://docs.vaultpanel.net/api-reference/settings#take-the-panel-off-its-domain) |
| GET | `/api/v1/settings/email` | [Get the email settings](https://docs.vaultpanel.net/api-reference/settings#get-the-email-settings) |
| PUT | `/api/v1/settings/email` | [Save the email settings](https://docs.vaultpanel.net/api-reference/settings#save-the-email-settings) |
| POST | `/api/v1/settings/email/test` | [Send a test email](https://docs.vaultpanel.net/api-reference/settings#send-a-test-email) |
| GET | `/api/v1/settings/email/messages` | [List sent email](https://docs.vaultpanel.net/api-reference/settings#list-sent-email) |

## Get the panel domain

`GET /api/v1/settings/panel-domain` — Permission: settings.manage — Token scope: full

The panel is put on a domain by a reverse-proxy website on **This server**, the server the panel runs on, which sends the domain's requests to the panel's port (its plain HTTP loopback port when the panel serves HTTPS itself). This returns that state:

| Field | Description |
| --- | --- |
| `domain` | The panel's domain, or `null`. |
| `removing` | Taking it off the domain was asked and is not finished (or failed). |
| `website` | The website that serves the domain, with its certificate under `ssl`. Certificates are managed through [Websites](https://docs.vaultpanel.net/api-reference/websites). |
| `server` | **This server**: `{ id, name, status, publicIp, ipAddresses, webStack }`, or `null` when it is not connected. |
| `defaultPort` | The port the website proxies to unless another is given. |
| `address` | `{ current, environment, usesDomain, canUseDomain }`: the panel's address now, the one in its `.env`, whether the domain is the address, and whether it can be (the website is active with a trusted, non-staging certificate). |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/settings/panel-domain \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const state = await panel.request('GET', '/settings/panel-domain');
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "domain": "cp.example.com",
    "removing": false,
    "website": { "id": "5d6e7f8a-…", "type": "proxy", "primaryDomain": "cp.example.com", "proxyPort": 8091, "status": "active" },
    "server": { "id": "9b2e7c1a-…", "name": "This server", "status": "online", "publicIp": "203.0.113.10", "ipAddresses": ["203.0.113.10"], "webStack": {} },
    "defaultPort": 8091,
    "address": {
      "current": "https://203.0.113.10:8090",
      "environment": "https://203.0.113.10:8090",
      "usesDomain": false,
      "canUseDomain": true
    }
  },
  "message": "OK",
  "requestId": "…"
}
```

## Put the panel on a domain

`PUT /api/v1/settings/panel-domain` — Permission: settings.manage — Token scope: full

Creates the panel's website on **This server** for the domain, or moves it to another domain or port. Point the domain's DNS at the server first, and install the web stack (NGINX and Certbot) on it. Moving to another domain sets the panel's address back to the one in `.env` until the new domain has a certificate. Then issue a certificate for the website and [use the domain as the address](https://docs.vaultpanel.net/api-reference/settings#use-the-domain-as-the-panels-address). See [Panel HTTPS and domain](https://docs.vaultpanel.net/getting-started/panel-https-and-domain).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | Yes | Such as `cp.example.com`. |
| `proxyPort` | integer | No | 1 to 65535. Default `defaultPort`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/settings/panel-domain \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "cp.example.com" }'
```

**JavaScript**

```js
const { job } = await panel.request('PUT', '/settings/panel-domain', { body: { domain: 'cp.example.com' } });
if (job) await panel.jobs.wait(job.id);
```

**Response** `202 Accepted` with the state and the website's `job` (message `The agent is putting the panel on the domain`), or `200 OK` with `job: null` when nothing changed (message `Nothing to change`).

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `NO_LOCAL_SERVER` | The panel's own server is not connected as **This server**. |
| 409 | `PANEL_WEBSITE_FAILED` | Setting up the current domain failed: send the same domain to try again, or remove it first. |
| 422 | `VALIDATION_ERROR` | An invalid domain or port, or the website could not be created with them. |

## Use the domain as the panel's address

`PUT /api/v1/settings/panel-domain/address` — Permission: settings.manage — Token scope: full

Makes `https://<domain>` the panel's address, so agent install commands, password reset links and deploy webhooks use it; or goes back to the address in `.env`. The IP address keeps working either way.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `use` | boolean | Yes | `true` uses the domain; `false` goes back to the `.env` address. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/settings/panel-domain/address \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "use": true }'
```

**JavaScript**

```js
await panel.request('PUT', '/settings/panel-domain/address', { body: { use: true } });
```

**Response** `200 OK`: the state, message `The panel's address is now …`.

**Errors**: `409 PANEL_DOMAIN_NOT_READY` when the domain has no trusted certificate yet (a staging one does not count: agents on other servers refuse untrusted certificates).

## Take the panel off its domain

`DELETE /api/v1/settings/panel-domain` — Permission: settings.manage — Token scope: full

Removes the panel's website (its NGINX configuration and certificate) from **This server** and sets the address back to the one in `.env`. The IP address keeps working.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/settings/panel-domain \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.request('DELETE', '/settings/panel-domain');
```

**Response** `200 OK`: the state with `removing: true` and the website's `job`, message `The panel is being taken off its domain`.

## Get the email settings

`GET /api/v1/settings/email` — Permission: settings.manage — Token scope: full

The SMTP server the panel sends its own email through: invites, password reset links and alert emails. The password is never returned (`hasPassword`). `missing` says what is still needed, and `ready` whether email is on and complete. See [Panel email](https://docs.vaultpanel.net/guides/dns-and-email/panel-email).

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/settings/email \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const settings = await panel.request('GET', '/settings/email');
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "enabled": true,
    "host": "smtp.example.com",
    "port": 587,
    "security": "starttls",
    "username": "panel@example.com",
    "hasPassword": true,
    "fromAddress": "panel@example.com",
    "fromName": "VaultPanel",
    "alerts": {
      "events": ["backup.failed", "restore.failed", "cron.failed", "deployment.failed", "alert.firing", "server.offline"],
      "toAdmins": true,
      "extra": []
    },
    "missing": null,
    "ready": true,
    "updatedAt": "2026-11-08T10:00:00.000Z"
  },
  "message": "OK",
  "requestId": "…"
}
```

## Save the email settings

`PUT /api/v1/settings/email` — Permission: settings.manage — Token scope: full

Saves any of the fields; the rest keep their values. Changing the host forgets the saved password unless a new one is given.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | No | Send email. Needs a host, port and from address (and a password with a username). |
| `host` | string | No | The SMTP host name or IP address, without scheme or port. |
| `port` | integer | No | 1 to 65535. |
| `security` | string | No | `tls` (encrypted from the start, usually 465), `starttls` (required upgrade, usually 587) or `none` (only for a mail server on the same machine or network). |
| `username` | string or null | No | Up to 254 characters. |
| `password` | string or null | No | Sets the password; `null` or empty removes it; leaving it out keeps it. |
| `fromAddress` | string | No | The address emails come from. |
| `fromName` | string | No | Up to 100 characters. Default `VaultPanel`. |
| `alerts` | object | No | `events` (the [webhook events](https://docs.vaultpanel.net/api-reference/webhooks#events) to email), `toAdmins` (send them to owners and admins) and `extra` (up to 10 more addresses). |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/settings/email \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "host": "smtp.example.com",
    "port": 587,
    "security": "starttls",
    "username": "panel@example.com",
    "password": "'"$SMTP_PASSWORD"'",
    "fromAddress": "panel@example.com"
  }'
```

**JavaScript**

```js
await panel.request('PUT', '/settings/email', {
  body: { alerts: { events: ['backup.failed', 'server.offline'], extra: ['oncall@example.com'] } },
});
```

**Response** `200 OK`: the settings, message `Email settings saved`.

**Errors**: `422 VALIDATION_ERROR` when turning email on with a setting missing, or an invalid field.

## Send a test email

`POST /api/v1/settings/email/test` — Permission: settings.manage — Token scope: full

Sends a test email now, with the saved settings or with settings being edited (merged over the saved ones, not saved).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `to` | string | Yes | Who receives it. |
| `settings` | object | No | Any of `host`, `port`, `security`, `username`, `password`, `fromAddress` and `fromName` to try. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/settings/email/test \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "owner@example.com" }'
```

**JavaScript**

```js
const { message } = await panel.request('POST', '/settings/email/test', { body: { to: 'owner@example.com' } });
```

**Response** `200 OK`: `{ message }`, the sent email (as in [List sent email](https://docs.vaultpanel.net/api-reference/settings#list-sent-email)), message `Test email sent to owner@example.com`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 422 | `EMAIL_NOT_SET_UP` | A setting is missing; the message says which. |
| 502 | `EMAIL_SEND_FAILED` | The mail server refused it or could not be reached; the message explains why. |

## List sent email

`GET /api/v1/settings/email/messages` — Permission: settings.manage — Token scope: full

The most recent email the panel sent or is trying to send, newest first. Messages that fail are retried after 1, 5 and 30 minutes, and are kept for 30 days.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | 1 to 200. Default 50. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/settings/email/messages?limit=20" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.request('GET', '/settings/email/messages', { query: { limit: 20 } });
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "f1e2d3c4-…",
        "to": "ada@example.org",
        "subject": "Your VaultPanel account",
        "purpose": "invite",
        "event": null,
        "status": "sent",
        "attempts": 1,
        "error": null,
        "nextAttemptAt": null,
        "sentAt": "2026-11-10T12:00:03.000Z",
        "createdAt": "2026-11-10T12:00:02.000Z"
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```
