# Email

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

> API reference for email hosting on your servers with Postfix, Dovecot and OpenDKIM - mail servers, email domains, mailboxes and forwarders.

Email hosting runs Postfix, Dovecot and OpenDKIM on your servers. Each server that hosts email has one mail server with a host name such as `mail.example.com`. The panel keeps its domains, mailboxes and forwarders: every change raises the mail server's serial and sends the whole set to the agent in a `MAIL_APPLY` job. Mailbox passwords are hashed by the panel (SHA512-CRYPT); only the hash ever reaches the server.

`/mail` is for staff: hosting customers are refused with `403 FORBIDDEN`. For the workflow in the panel, see [Email hosting](https://docs.vaultpanel.net/guides/dns-and-email/email-hosting).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/mail/servers` | [List mail servers](https://docs.vaultpanel.net/api-reference/mail#list-mail-servers) |
| POST | `/api/v1/mail/servers` | [Set up a mail server](https://docs.vaultpanel.net/api-reference/mail#set-up-a-mail-server) |
| POST | `/api/v1/mail/servers/:serverId/apply` | [Apply the settings again](https://docs.vaultpanel.net/api-reference/mail#apply-the-settings-again) |
| POST | `/api/v1/mail/servers/:serverId/check` | [Check the host name in public DNS](https://docs.vaultpanel.net/api-reference/mail#check-the-host-name-in-public-dns) |
| POST | `/api/v1/mail/servers/:serverId/usage` | [Refresh mailbox sizes](https://docs.vaultpanel.net/api-reference/mail#refresh-mailbox-sizes) |
| GET | `/api/v1/mail/domains` | [List email domains](https://docs.vaultpanel.net/api-reference/mail#list-email-domains) |
| POST | `/api/v1/mail/domains` | [Add an email domain](https://docs.vaultpanel.net/api-reference/mail#add-an-email-domain) |
| GET | `/api/v1/mail/domains/:id` | [Get an email domain](https://docs.vaultpanel.net/api-reference/mail#get-an-email-domain) |
| DELETE | `/api/v1/mail/domains/:id` | [Remove an email domain](https://docs.vaultpanel.net/api-reference/mail#remove-an-email-domain) |
| POST | `/api/v1/mail/domains/:id/dns` | [Add the DNS records to the zone](https://docs.vaultpanel.net/api-reference/mail#add-the-dns-records-to-the-zone) |
| POST | `/api/v1/mail/domains/:id/check` | [Check the domain's records in public DNS](https://docs.vaultpanel.net/api-reference/mail#check-the-domains-records-in-public-dns) |
| POST | `/api/v1/mail/domains/:id/mailboxes` | [Add a mailbox](https://docs.vaultpanel.net/api-reference/mail#add-a-mailbox) |
| PATCH | `/api/v1/mail/domains/:id/mailboxes/:itemId` | [Update a mailbox](https://docs.vaultpanel.net/api-reference/mail#update-a-mailbox) |
| DELETE | `/api/v1/mail/domains/:id/mailboxes/:itemId` | [Delete a mailbox](https://docs.vaultpanel.net/api-reference/mail#delete-a-mailbox) |
| POST | `/api/v1/mail/domains/:id/forwarders` | [Add a forwarder](https://docs.vaultpanel.net/api-reference/mail#add-a-forwarder) |
| PATCH | `/api/v1/mail/domains/:id/forwarders/:itemId` | [Update a forwarder](https://docs.vaultpanel.net/api-reference/mail#update-a-forwarder) |
| DELETE | `/api/v1/mail/domains/:id/forwarders/:itemId` | [Delete a forwarder](https://docs.vaultpanel.net/api-reference/mail#delete-a-forwarder) |

Changes return `202 Accepted` with the `job` that sends them. `job` is `null` when an apply is already on its way: the change is sent right after it.

## Objects

**Mail server**

| Field | Type | Description |
| --- | --- | --- |
| `id`, `serverId` | string | The mail server, and the server it runs on. |
| `hostname` | string | The host name mail clients and other mail servers use. |
| `status` | string | `setting_up`, `active` or `failed`. |
| `tls` | object or null | The certificate the agent reported for the host name. |
| `serial`, `appliedSerial`, `appliedAt` | | The settings' serial, the serial the server confirmed and when. |
| `pending` | boolean | The server does not have the latest changes yet. |
| `applying`, `settingUp` | boolean | A `MAIL_APPLY` or `MAIL_SETUP` job is queued or running. |
| `checks`, `checkedAt` | object | The last [host name check](https://docs.vaultpanel.net/api-reference/mail#check-the-host-name-in-public-dns). |
| `lastJobId`, `lastError` | | The last job, and `{ code, message }` of the last failure. |

**Email domain**: `id`, `serverId`, `serverName`, `hostname` (its mail server's), `domain`, `status` (`active` or `deleting`), `autoDns` (records are kept in the panel's DNS zone), `dkimSelector` (`vaultpanel`), `dkimReady` (the server made the DKIM key), `mailboxCount`, `forwarderCount`, `createdAt`. A single domain also has `mailboxes`, `forwarders`, `mailServer`, `client` (the settings for mail apps) and `dns` (the records it needs, each with a `state` of `ok`, `different`, `missing` or `no_zone`, and `dkimPending`).

**Mailbox**: `id`, `domainId`, `localPart`, `address`, `displayName`, `quotaMb`, `enabled`, `usedBytes` and `usageCheckedAt` (from the last [size refresh](https://docs.vaultpanel.net/api-reference/mail#refresh-mailbox-sizes)), `createdAt`, `updatedAt`.

**Forwarder**: `id`, `domainId`, `localPart`, `address`, `destinations`, `createdAt`, `updatedAt`.

## List mail servers

`GET /api/v1/mail/servers` — Permission: mail.read — Token scope: read

Returns every server with its mail server, if it has one: `serverId`, `serverName`, `serverStatus`, `agent` (what the agent reports about mail software, `null` when the agent is too old to host email), `addresses` (`{ ipv4, ipv6 }`), `suggestedHostname`, `domainCount` and `mailServer`.

**Example request**

**cURL**

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

**JavaScript**

```js
const { items } = await panel.mail.servers();
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
        "serverName": "web-1",
        "serverStatus": "online",
        "addresses": { "ipv4": "203.0.113.10", "ipv6": null },
        "suggestedHostname": "web-1.example.com",
        "domainCount": 1,
        "mailServer": {
          "id": "61f0a2b3-…",
          "serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
          "hostname": "mail.example.com",
          "status": "active",
          "serial": 12,
          "appliedSerial": 12,
          "pending": false,
          "applying": false,
          "settingUp": false,
          "lastError": null
        }
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

## Set up a mail server

`POST /api/v1/mail/servers` — Permission: mail.manage — Token scope: manage

Installs and configures the mail software on a server (a `MAIL_SETUP` job), or sets it up again with a new host name. When the panel runs the DNS zone for the host name and the zone has no address for it yet, an `A` (and `AAAA`) record for the server is added.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `serverId` | string (UUID) | Yes | The server. |
| `hostname` | string | Yes | The mail host name, such as `mail.example.com`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/servers \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c", "hostname": "mail.example.com" }'
```

**JavaScript**

```js
const { mailServer, job } = await panel.mail.setupServer({
  serverId: '9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c',
  hostname: 'mail.example.com',
});
```

**Response** `202 Accepted`: `{ mailServer, job }`, message `Setting up the mail server`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `SERVER_NOT_READY` | The server has no connected agent yet. |
| 409 | `AGENT_OUTDATED` | The server's agent is too old to host email. |
| 409 | `MAIL_BUSY` | A set-up is already running (`details.jobId`). |
| 422 | `VALIDATION_ERROR` | Invalid host name, or the server does not exist. |

## Apply the settings again

`POST /api/v1/mail/servers/:serverId/apply` — Permission: mail.manage — Token scope: manage

Sends every domain, mailbox and forwarder of the server again, for example after a failure or to put back files someone changed by hand. Clears the last error.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/apply \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.request('POST', `/mail/servers/${serverId}/apply`);
```

**Response** `202 Accepted`: `{ mailServer, job }`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `MAIL_NOT_SET_UP` | The server has no mail server set up. |
| 409 | `MAIL_BUSY` | A set-up or apply is running (`details.jobId`). |

## Check the host name in public DNS

`POST /api/v1/mail/servers/:serverId/check` — Permission: mail.read — Token scope: read

Asks public DNS whether the host name points at the server (`forward`) and whether the server's IPv4 address points back at the host name (`reverse`, which many receiving servers check). The result is saved as the mail server's `checks`.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/check \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { mailServer } = await panel.request('POST', `/mail/servers/${serverId}/check`);
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "mailServer": {
      "hostname": "mail.example.com",
      "checks": {
        "hostname": "mail.example.com",
        "address": "203.0.113.10",
        "forward": { "ok": true, "found": ["203.0.113.10"] },
        "reverse": { "ok": false, "found": ["203-0-113-10.provider.example"] }
      },
      "checkedAt": "2026-11-10T10:00:00.000Z"
    }
  },
  "message": "OK",
  "requestId": "…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `MAIL_NOT_SET_UP` | The server has no mail server set up. |

## Refresh mailbox sizes

`POST /api/v1/mail/servers/:serverId/usage` — Permission: mail.read — Token scope: read

Queues a `MAIL_USAGE` job that asks the server how much mail each mailbox holds. When it finishes, each mailbox's `usedBytes` and `usageCheckedAt` are updated. If the same job is already running, its id is returned.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/usage \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { job } = await panel.request('POST', `/mail/servers/${serverId}/usage`);
await panel.jobs.wait(job.id);
```

**Response** `202 Accepted`: `{ job }`, message `Checking mailbox sizes`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `MAIL_NOT_SET_UP` | The server has no mail server set up. |

## List email domains

`GET /api/v1/mail/domains` — Permission: mail.read — Token scope: read

Returns email domains a page at a time, with their mailbox and forwarder counts.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | No | Part of the domain, up to 100 characters. |
| `serverId` | string (UUID) | No | Only domains on this server. |
| `page`, `pageSize` | integer | No | Page from 1; 1 to 100 per page (default 25). |
| `sort`, `order` | string | No | `domain` (default) or `createdAt`; `asc` (default) or `desc`. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/mail/domains?serverId=9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.mail.domains({ serverId });
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "a1b2c3d4-…",
        "serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
        "serverName": "web-1",
        "hostname": "mail.example.com",
        "domain": "example.com",
        "status": "active",
        "autoDns": true,
        "dkimSelector": "vaultpanel",
        "dkimReady": true,
        "mailboxCount": 3,
        "forwarderCount": 1,
        "createdAt": "2026-11-01T12:00:00.000Z"
      }
    ],
    "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
  },
  "message": "OK",
  "requestId": "…"
}
```

## Add an email domain

`POST /api/v1/mail/domains` — Permission: mail.manage — Token scope: manage

Adds a domain to a server's mail server. With `addDnsRecords` (the default), the panel puts the `MX`, SPF and DMARC records into its DNS zone for the domain, replacing an existing `MX` and SPF record, and adds the DKIM record once the server has made the key. A server hosts email for up to 200 domains.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `serverId` | string (UUID) | Yes | A server with a mail server set up. |
| `domain` | string | Yes | The email domain, such as `example.com`. |
| `addDnsRecords` | boolean | No | Add the records to the panel's DNS zone for the domain. Default `true`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/domains \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c", "domain": "example.com" }'
```

**JavaScript**

```js
const { domain, job, dnsZone } = await panel.mail.createDomain({
  serverId: '9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c',
  domain: 'example.com',
});
```

**Response** `202 Accepted`: `{ domain, job, dnsZone }`. `dnsZone` is `{ id, domain, added }` when records went into a panel zone, otherwise `null`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `SERVER_NOT_READY`, `AGENT_OUTDATED` | The server cannot host email. |
| 409 | `MAIL_NOT_SET_UP` | The server has no mail server set up. |
| 422 | `VALIDATION_ERROR` | The domain already has email in the panel, the server already has 200 domains, or a field is invalid. |

## Get an email domain

`GET /api/v1/mail/domains/:id` — Permission: mail.read — Token scope: read

Returns the domain with its mailboxes, forwarders, mail server, mail app settings and the DNS records it needs.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const domain = await panel.mail.domain(domainId);
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "domain": "example.com",
    "hostname": "mail.example.com",
    "status": "active",
    "dkimReady": true,
    "mailboxes": [
      { "id": "…", "localPart": "hello", "address": "hello@example.com", "displayName": "Hello", "quotaMb": 1024, "enabled": true, "usedBytes": 5242880, "usageCheckedAt": "2026-11-10T10:05:00.000Z" }
    ],
    "forwarders": [
      { "id": "…", "localPart": "sales", "address": "sales@example.com", "destinations": ["team@example.org"] }
    ],
    "client": {
      "hostname": "mail.example.com",
      "incoming": [
        { "protocol": "IMAP", "port": 993, "security": "SSL/TLS" },
        { "protocol": "POP3", "port": 995, "security": "SSL/TLS" }
      ],
      "outgoing": [
        { "protocol": "SMTP", "port": 587, "security": "STARTTLS" },
        { "protocol": "SMTP", "port": 465, "security": "SSL/TLS" }
      ],
      "username": "The full email address"
    },
    "dns": {
      "zone": { "id": "4f0c2a8e-…", "domain": "example.com" },
      "records": [
        { "name": "@", "type": "MX", "value": "mail.example.com", "priority": 10, "purpose": "mx", "state": "ok" },
        { "name": "@", "type": "TXT", "value": "v=spf1 mx ~all", "purpose": "spf", "state": "ok" },
        { "name": "_dmarc", "type": "TXT", "value": "v=DMARC1; p=none", "purpose": "dmarc", "state": "ok" }
      ],
      "dkimPending": false
    }
  },
  "message": "OK",
  "requestId": "…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No email domain with this id. |

## Remove an email domain

`DELETE /api/v1/mail/domains/:id` — Permission: mail.manage — Token scope: manage

Marks the domain `deleting` and sends the change. By default the domain's stored mail is deleted from the server too.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `deleteMail` | `true` or `false` | No | Delete the stored mail. Default `true`. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d?deleteMail=false" \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.mail.removeDomain(domainId, { deleteMail: 'false' });
```

**Response** `202 Accepted`: `{ domain, job }`, message `Removing the domain`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No email domain with this id. |
| 409 | `MAIL_DOMAIN_DELETING` | The domain is already being removed. |

## Add the DNS records to the zone

`POST /api/v1/mail/domains/:id/dns` — Permission: mail.manage, dns.manage — Token scope: manage

Puts the domain's `MX`, SPF, DKIM (when ready) and DMARC records into the panel's DNS zone for the domain now, replacing an existing `MX` record and SPF, DKIM or DMARC record of the same kind, and turns `autoDns` on.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/dns \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { dnsZone } = await panel.request('POST', `/mail/domains/${domainId}/dns`);
```

**Response** `202 Accepted`: `{ domain, dnsZone: { id, domain, added, removed }, job }`, message `Records added to the DNS zone`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No email domain with this id. |
| 409 | `NO_DNS_ZONE` | The panel does not run DNS for the domain: add the records where its DNS is hosted. |

## Check the domain's records in public DNS

`POST /api/v1/mail/domains/:id/check` — Permission: mail.read — Token scope: read

Looks up each record the domain needs in public DNS. Each record gets `public: { found, state }` with `state` `ok`, `different`, `missing` or `error`.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/check \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { records } = await panel.mail.checkDns(domainId);
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "records": [
      { "name": "@", "type": "MX", "value": "mail.example.com", "priority": 10, "purpose": "mx", "public": { "found": ["mail.example.com"], "state": "ok" } },
      { "name": "_dmarc", "type": "TXT", "value": "v=DMARC1; p=none", "purpose": "dmarc", "public": { "found": [], "state": "missing" } }
    ],
    "checkedAt": "2026-11-10T10:10:00.000Z"
  },
  "message": "OK",
  "requestId": "…"
}
```

## Add a mailbox

`POST /api/v1/mail/domains/:id/mailboxes` — Permission: mail.manage — Token scope: manage

Adds a mailbox. When no password is given, the panel generates one and returns it in this response only. A server holds up to 2000 mailboxes.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `localPart` | string | Yes | The part before `@`. Must not be an existing mailbox or forwarder. |
| `password` | string | No | 10 to 128 characters, one line. Generated when left out. |
| `displayName` | string or null | No | Up to 100 characters. |
| `quotaMb` | integer | No | 0 to 1048576. Default 1024. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/mailboxes \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "localPart": "hello", "displayName": "Hello", "quotaMb": 2048 }'
```

**JavaScript**

```js
const { mailbox, password } = await panel.mail.createMailbox(domainId, {
  localPart: 'hello',
  displayName: 'Hello',
  quotaMb: 2048,
});
```

**Response** `202 Accepted`

```json
{
  "success": true,
  "data": {
    "mailbox": { "id": "…", "localPart": "hello", "address": "hello@example.com", "displayName": "Hello", "quotaMb": 2048, "enabled": true, "usedBytes": null },
    "password": "kq3T9vX2mPz7Lw4Rb8Ns",
    "domain": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "domain": "example.com" },
    "job": { "id": "…", "type": "MAIL_APPLY", "status": "queued" }
  },
  "message": "Mailbox added",
  "requestId": "…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No email domain with this id. |
| 409 | `MAIL_DOMAIN_DELETING` | The domain is being removed. |
| 422 | `VALIDATION_ERROR` | The address is already a mailbox or forwarder, the server has 2000 mailboxes, or a field is invalid. |

## Update a mailbox

`PATCH /api/v1/mail/domains/:id/mailboxes/:itemId` — Permission: mail.manage — Token scope: manage

Changes a mailbox. Send at least one field. Use either `password` or `generatePassword`, not both; a generated password is returned in this response only.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `password` | string | No | A new password, 10 to 128 characters. |
| `generatePassword` | boolean | No | Generate a new password. |
| `displayName` | string or null | No | Up to 100 characters. |
| `quotaMb` | integer | No | 0 to 1048576. |
| `enabled` | boolean | No | `false` turns the mailbox off. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/mailboxes/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9 \
  -X PATCH \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "generatePassword": true }'
```

**JavaScript**

```js
const { password } = await panel.mail.updateMailbox(domainId, mailboxId, { generatePassword: true });
```

**Response** `202 Accepted`: `{ mailbox, password, domain, job }`; `password` only with `generatePassword`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such domain or mailbox. |
| 409 | `MAIL_DOMAIN_DELETING` | The domain is being removed. |
| 422 | `VALIDATION_ERROR` | No field given, both `password` and `generatePassword`, or a field is invalid. |

## Delete a mailbox

`DELETE /api/v1/mail/domains/:id/mailboxes/:itemId` — Permission: mail.manage — Token scope: manage

Deletes the mailbox. By default its stored mail is deleted from the server too.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `deleteMail` | `true` or `false` | No | Delete the stored mail. Default `true`. |

**Example request**

**cURL**

```bash
curl -X DELETE \
  https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/mailboxes/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9 \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.mail.removeMailbox(domainId, mailboxId);
```

**Response** `202 Accepted`: `{ domain, job }`, message `Mailbox deleted`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such domain or mailbox. |
| 409 | `MAIL_DOMAIN_DELETING` | The domain is being removed. |

## Add a forwarder

`POST /api/v1/mail/domains/:id/forwarders` — Permission: mail.manage — Token scope: manage

Adds an address that forwards mail to other addresses. A server holds up to 2000 forwarders.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `localPart` | string | Yes | The part before `@`. Must not be an existing mailbox or forwarder. |
| `destinations` | string[] | Yes | 1 to 20 email addresses. Duplicates are dropped; the forwarder's own address is refused. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/forwarders \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "localPart": "sales", "destinations": ["team@example.org"] }'
```

**JavaScript**

```js
const { forwarder } = await panel.mail.createForwarder(domainId, {
  localPart: 'sales',
  destinations: ['team@example.org'],
});
```

**Response** `202 Accepted`: `{ forwarder, domain, job }`, message `Forwarder added`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No email domain with this id. |
| 409 | `MAIL_DOMAIN_DELETING` | The domain is being removed. |
| 422 | `VALIDATION_ERROR` | The address is taken, a destination is invalid or is the forwarder itself, or the server has 2000 forwarders. |

## Update a forwarder

`PATCH /api/v1/mail/domains/:id/forwarders/:itemId` — Permission: mail.manage — Token scope: manage

Replaces the forwarder's destinations.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `destinations` | string[] | Yes | 1 to 20 email addresses. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/forwarders/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
  -X PATCH \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "destinations": ["team@example.org", "boss@example.org"] }'
```

**JavaScript**

```js
await panel.request('PATCH', `/mail/domains/${domainId}/forwarders/${forwarderId}`, {
  body: { destinations: ['team@example.org', 'boss@example.org'] },
});
```

**Response** `202 Accepted`: `{ forwarder, domain, job }`, message `Forwarder saved`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such domain or forwarder. |
| 409 | `MAIL_DOMAIN_DELETING` | The domain is being removed. |
| 422 | `VALIDATION_ERROR` | A destination is invalid or is the forwarder itself. |

## Delete a forwarder

`DELETE /api/v1/mail/domains/:id/forwarders/:itemId` — Permission: mail.manage — Token scope: manage

Deletes the forwarder.

**Example request**

**cURL**

```bash
curl -X DELETE \
  https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/forwarders/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.mail.removeForwarder(domainId, forwarderId);
```

**Response** `202 Accepted`: `{ domain, job }`, message `Forwarder deleted`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such domain or forwarder. |
| 409 | `MAIL_DOMAIN_DELETING` | The domain is being removed. |
