# dms-api

HTTPS admin API for a remote `docker-mailserver` (DMS) container. Replaces
SSH-based admin scripts with a single bearer-token REST API.

## Architecture

```
+--------------+   HTTPS   +-----------+   unix socket   +-----------------+
| dms-ui / mcp | --------> |  dms-api | -------------> | docker-mailserver |
| (any host)   |  bearer   |  (host)  |  docker exec   |   (mailserver)    |
+--------------+           +-----------+                 +-----------------+
```

## Quick install (on the mail host)

```bash
export DMS_API_TOKEN="$(openssl rand -hex 24)"   # save this — it's the only auth
./install.sh
```

## Front with Caddy (auto-LE)

```bash
sudo cp Caddyfile.example /etc/caddy/Caddyfile
sudo sed -i 's/dms.example.com/dms.vibecode.icu/' /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

## Endpoints

All require `Authorization: Bearer <DMS_API_TOKEN>` except `/health`.

| Method | Path | Body | Action |
|---|---|---|---|
| GET    | /health                                  |     | liveness (no auth) |
| GET    | /health/auth                             |     | verifies token |
| GET    | /v1/dashboard                            |     | container + queue + account count + disk + log tail |
| GET    | /v1/accounts                             |     | list accounts |
| POST   | /v1/accounts                             | {email,password,quota?} | create account |
| POST   | /v1/accounts/{email}/password            | {password} | change password |
| DELETE | /v1/accounts/{email}                     |     | delete account |
| GET    | /v1/aliases                              |     | list aliases |
| POST   | /v1/aliases                              | {source,target} | add alias |
| DELETE | /v1/aliases                              | {source,target} | remove alias |
| GET    | /v1/quotas                               |     | list per-account quota |
| POST   | /v1/quotas                               | {email,quota} | set quota |
| DELETE | /v1/quotas/{email}                      |     | remove quota |
| GET    | /v1/queue                                |     | postqueue -p |
| POST   | /v1/queue/flush                          |     | postqueue -f |
| GET    | /v1/logs/tail?n=200                      |     | tail /var/log/mail.log |
| POST   | /v1/raw                                  | {subcommand} | whitelisted escape hatch |

## Security

* HTTPS via reverse proxy (Caddy auto-LE).
* api binds 127.0.0.1; never expose 8791 directly.
* Single shared `DMS_API_TOKEN`; rotate by recreating the container.
* 30 req/sec per IP rate limit.
* `POST /v1/raw` only accepts `setup / postqueue / doveadm / dms-healthcheck`.
* `docker.sock` mounted read-only.