TypeScript wrapper for the mailcow API

Typed, promise-based client for the Mailcow API.

• Node 22+
• Single runtime dependency (axios)
• Full typedoc reference: https://justsamuel.github.io/ts-mailcow-api/classes/MailcowClient.html

Install

yarn add ts-mailcow-api
# or
npm install ts-mailcow-api
Copy

Usage

Create a client with a base URL and API key:

import MailcowClient from "ts-mailcow-api";

const mcc = new MailcowClient(
  "https://demo.mailcow.email/api/v1",
  "390448-22B69F-FA37D9-19701B-6F033F",
);
Copy

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:

const mailboxes = await mcc.mailbox.get("all");
console.log(mailboxes);
Copy

Custom axios config (self-signed certs, proxies, keep-alive)

The third constructor argument is forwarded into the underlying axios config:

import https from "node:https";

const mcc = new MailcowClient(BASE_URL, API_KEY, {
  httpsAgent: new https.Agent({ rejectUnauthorized: false }),
  timeout: 10_000,
});
Copy

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:

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;
  }
}
Copy

Endpoint groups

The MailcowClient exposes one property per Mailcow resource. Each one points at a typed interface documented in the typedoc reference.

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 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.