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.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/mail/servers | List mail servers |
| POST | /api/v1/mail/servers | Set up a mail server |
| POST | /api/v1/mail/servers/:serverId/apply | Apply the settings again |
| POST | /api/v1/mail/servers/:serverId/check | Check the host name in public DNS |
| POST | /api/v1/mail/servers/:serverId/usage | Refresh mailbox sizes |
| GET | /api/v1/mail/domains | List email domains |
| POST | /api/v1/mail/domains | Add an email domain |
| GET | /api/v1/mail/domains/:id | Get an email domain |
| DELETE | /api/v1/mail/domains/:id | Remove an email domain |
| POST | /api/v1/mail/domains/:id/dns | Add the DNS records to the zone |
| POST | /api/v1/mail/domains/:id/check | Check the domain's records in public DNS |
| POST | /api/v1/mail/domains/:id/mailboxes | Add a mailbox |
| PATCH | /api/v1/mail/domains/:id/mailboxes/:itemId | Update a mailbox |
| DELETE | /api/v1/mail/domains/:id/mailboxes/:itemId | Delete a mailbox |
| POST | /api/v1/mail/domains/:id/forwarders | Add a forwarder |
| PATCH | /api/v1/mail/domains/:id/forwarders/:itemId | Update a forwarder |
| DELETE | /api/v1/mail/domains/:id/forwarders/:itemId | 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. |
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), createdAt, updatedAt.
Forwarder: id, domainId, localPart, address, destinations, createdAt, updatedAt.
List mail servers
/api/v1/mail/serversReturns 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 https://panel.example.com/api/v1/mail/servers \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.mail.servers();Response 200 OK
{
"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
/api/v1/mail/serversInstalls 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 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" }'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
/api/v1/mail/servers/:serverId/applySends 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 https://panel.example.com/api/v1/mail/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/apply \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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
/api/v1/mail/servers/:serverId/checkAsks 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 https://panel.example.com/api/v1/mail/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/check \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { mailServer } = await panel.request('POST', `/mail/servers/${serverId}/check`);Response 200 OK
{
"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
/api/v1/mail/servers/:serverId/usageQueues 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 https://panel.example.com/api/v1/mail/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/usage \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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
/api/v1/mail/domainsReturns 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 "https://panel.example.com/api/v1/mail/domains?serverId=9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.mail.domains({ serverId });Response 200 OK
{
"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
/api/v1/mail/domainsAdds 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 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" }'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
/api/v1/mail/domains/:idReturns the domain with its mailboxes, forwarders, mail server, mail app settings and the DNS records it needs.
Example request
curl https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const domain = await panel.mail.domain(domainId);Response 200 OK
{
"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
/api/v1/mail/domains/:idMarks 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 "https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d?deleteMail=false" \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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
/api/v1/mail/domains/:id/dnsPuts 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 https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/dns \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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
/api/v1/mail/domains/:id/checkLooks 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 https://panel.example.com/api/v1/mail/domains/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/check \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { records } = await panel.mail.checkDns(domainId);Response 200 OK
{
"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
/api/v1/mail/domains/:id/mailboxesAdds 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 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 }'const { mailbox, password } = await panel.mail.createMailbox(domainId, {
localPart: 'hello',
displayName: 'Hello',
quotaMb: 2048,
});Response 202 Accepted
{
"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
/api/v1/mail/domains/:id/mailboxes/:itemIdChanges 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 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 }'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
/api/v1/mail/domains/:id/mailboxes/:itemIdDeletes 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 -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"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
/api/v1/mail/domains/:id/forwardersAdds 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 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"] }'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
/api/v1/mail/domains/:id/forwarders/:itemIdReplaces the forwarder's destinations.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
destinations | string[] | Yes | 1 to 20 email addresses. |
Example request
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"] }'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
/api/v1/mail/domains/:id/forwarders/:itemIdDeletes the forwarder.
Example request
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"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. |