ts-mailcow-api
Version:
TypeScript wrapper for the mailcow API.
120 lines (93 loc) • 4.44 kB
Markdown
# TypeScript wrapper for the mailcow API
[](https://www.npmjs.com/package/ts-mailcow-api)
[](https://github.com/JustSamuel/ts-mailcow-api/actions/workflows/lint-and-build.yml)
[](https://github.com/JustSamuel/ts-mailcow-api/blob/master/LICENSE)
[](https://www.npmjs.com/package/ts-mailcow-api)
[](https://justsamuel.github.io/ts-mailcow-api/classes/MailcowClient.html)
Typed, promise-based client for the [Mailcow API](https://mailcow.docs.apiary.io/#).
- Node 22+
- Single runtime dependency (`axios`)
- Full typedoc reference: https://justsamuel.github.io/ts-mailcow-api/classes/MailcowClient.html
## Install
```bash
yarn add ts-mailcow-api
# or
npm install ts-mailcow-api
```
## Usage
Create a client with a base URL and API key:
```ts
import MailcowClient from "ts-mailcow-api";
const mcc = new MailcowClient(
"https://demo.mailcow.email/api/v1",
"390448-22B69F-FA37D9-19701B-6F033F",
);
```
> The key above is the public Mailcow demo key, shared with anyone testing
> against `demo.mailcow.email`. Do not copy it into production code.
Then call any endpoint group as a promise:
```ts
const mailboxes = await mcc.mailbox.get("all");
console.log(mailboxes);
```
### Custom axios config (self-signed certs, proxies, keep-alive)
The third constructor argument is forwarded into the underlying axios config:
```ts
import https from "node:https";
const mcc = new MailcowClient(BASE_URL, API_KEY, {
httpsAgent: new https.Agent({ rejectUnauthorized: false }),
timeout: 10_000,
});
```
### Error handling
Mailcow returns errors as a 2XX response with `type: "danger"` or
`type: "error"` in the body. This client unwraps that into a thrown
`MailcowException`, so a single `try / catch` works for both transport-level
and API-level failures:
```ts
import { MailcowException } from "ts-mailcow-api";
try {
await mcc.aliases.create({ /* ... */ });
} catch (e) {
if (e instanceof MailcowException) {
console.error("Mailcow rejected the request:", e.message);
} else {
throw e;
}
}
```
## Endpoint groups
The `MailcowClient` exposes one property per Mailcow resource. Each one points
at a typed interface documented in the
[typedoc reference](https://justsamuel.github.io/ts-mailcow-api/classes/MailcowClient.html).
| Property | Resource |
| ------------------ | --------------------------------- |
| `addressRewriting` | BCC and recipient maps |
| `aliases` | Aliases |
| `appPasswords` | App passwords |
| `dkim` | DKIM keys |
| `domainAdmins` | Domain administrators |
| `domains` | Domains |
| `fail2Ban` | Fail2Ban configuration |
| `forwardingHosts` | Forwarding hosts |
| `identityProvider` | External IdP (Keycloak/LDAP/OIDC) |
| `logs` | ACME, API, dovecot, postfix, ... |
| `mailbox` | Mailboxes (and ACL, pushover, ...)|
| `oauth2` | OAuth2 clients |
| `quarantine` | Quarantine |
| `queueManager` | Mail queue |
| `ratelimits` | Domain and mailbox rate limits |
| `resources` | Shared resources |
| `routing` | Relay hosts and transport maps |
| `spamPolicy` | Anti-spam policies |
| `status` | Container, vmail, version status |
| `syncjobs` | IMAP sync jobs |
| `tlsPolicyMaps` | TLS policy maps |
## Why this is not auto-generated
The [Mailcow OpenAPI spec](https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/api/openapi.yaml)
does not pass validation and is not RESTful (for example, `POST /api/v1/add/domain`).
If Mailcow ever fixes the naming or structure, a generated client would break.
This wrapper acts as a middleman, so those changes can be patched internally
without ruining the client interface.
## License
[AGPL-3.0-only](LICENSE).