# ts-mailcow-api > TypeScript wrapper for the mailcow API. Latest version **1.9.0** (published 2026-08-13) · AGPL-3.0-only license · 0 weekly downloads ## Install ```sh npm install ts-mailcow-api pnpm add ts-mailcow-api yarn add ts-mailcow-api bun add ts-mailcow-api ``` ## Health **Score 70/100 (B)** — status: active. Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score. Warnings: low downloads; no esm support. ## Facts | | | |---|---| | Version | 1.9.0 | | Published | 2026-08-13 | | First published | 2021-05-12 | | Weekly downloads | 0 | | License | AGPL-3.0-only | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 1 | | Unpacked size | 196.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | Author | Samuel | | Maintainers | justsamuel | | Keywords | mailcow, typescript, API | ## Links - npm: https://www.npmjs.com/package/ts-mailcow-api - Repository: https://github.com/JustSamuel/ts-mailcow-api - Homepage: https://github.com/JustSamuel/ts-mailcow-api#readme - Issues: https://github.com/JustSamuel/ts-mailcow-api/issues - npm.io page: https://npm.io/package/ts-mailcow-api ## Dependencies (1) - [axios](https://npm.io/package/axios.md) ^1.9.0 ## Alternatives - [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads - [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads - [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads - [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads - [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads ## Recent versions - 1.9.0 (latest) — 2026-08-13 - 1.8.0 — 2026-08-13 - 1.7.0 — 2026-08-06 - 1.6.0 — 2026-05-20 - 1.5.0 — 2026-05-20 - 1.4.0 — 2026-05-19 - 1.3.0 — 2026-05-19 - 1.2.1 — 2026-03-04 - 1.2.0 — 2026-01-15 - 1.1.0 — 2025-07-05 - 1.0.0 — 2025-06-13 - 0.12.0 — 2025-06-13 - 0.11.0 — 2025-06-11 - 0.10.0 — 2025-06-11 - 0.9.0 — 2024-09-25 - … 23 more at https://npm.io/package/ts-mailcow-api/versions ## README # TypeScript wrapper for the mailcow API [![npm version](https://img.shields.io/npm/v/ts-mailcow-api)](https://www.npmjs.com/package/ts-mailcow-api) [![Build Status](https://github.com/JustSamuel/ts-mailcow-api/actions/workflows/lint-and-build.yml/badge.svg)](https://github.com/JustSamuel/ts-mailcow-api/actions/workflows/lint-and-build.yml) [![License](https://img.shields.io/npm/l/ts-mailcow-api)](https://github.com/JustSamuel/ts-mailcow-api/blob/master/LICENSE) [![Downloads](https://img.shields.io/npm/dt/ts-mailcow-api)](https://www.npmjs.com/package/ts-mailcow-api) [![GitHub Pages](https://img.shields.io/badge/view-GitHub%20Pages-blue?logo=github)](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). --- _Source: https://npm.io/package/ts-mailcow-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._