This is a mirror of git.y.gy/firstdorsal/mailcow-api

Mailcow Api

A wrapper for the mailcow web API with the most relevant functions.

Install

npm i mailcow-api

Basic Example

(async () => {
    //get global variables
    require('dotenv').config();
    
    //import the api client module
    const {
        MailcowApiClient
    } = require("mailcow-api")

    //create new mailcow api client with endpoint/baseurl and the api key
    const mcc = new MailcowApiClient(process.env.MAILCOW_API_BASEURL, process.env.MAILCOW_API_KEY);

    //get all domain on mailcow server
    console.log(await mcc.getDomain());
})();

What is dotenv?

The line "require('dotenv').config();" gets the contents of a file called ".env" in which you should store your global and secret variables.

1. Install the module "dotenv" with

npm i dotenv

2. Create a file named ".env" in your applications root directory

.env

MAILCOW_API_KEY='YOUR MAILCOW API KEY'
MAILCOW_API_BASEURL='https://mail.example.com' //no trailing slashes

3. Use your secret variables

process.env.MAILCOW_API_BASEURL
process.env.MAILCOW_API_KEY

Where to get the API key?

1. Open your mailcow UI and login as admin

1.1 Are you using two factor authentication for your admin account?

If not: Do it now! It's easy! For Android you can use the andOTP app. andOTP can be used for 2FA with many services and is way better then the Google Authenticator app.

2. Scroll to and expand the API section

3. Insert the IP you want to accesss the API from or disable the API check

4. Tick the checkbox "Activate API" and save the settings

5. Copy your API key from the field above

Documentation

Here

Need help or missing a feature?

Feel free to contact me via xl9jthv_7bvgakv9o9wg0jabn2ylm91xxrzzgt0e@y.gy in english or german

Mailcow API Documentation

Apiary

Swagger

Links

NPM

Documentation

Code

Modules

mailcow-api

Typedefs

Domain : Object: For all options check out https://demo.mailcow.email/api/
DKIM : Object: Object representing a DKIM Key
DomainAdmin : Object: Object representing a domain admin
Mailbox : Object: Object representing a mailbox

mailcow-api

mailcow-api
- .MailcowApiClient
  - new module.exports.MailcowApiClient(baseurl, apikey)
  - .getDomain([domain]) ⇒ Array
  - .addDomain(domain) ⇒ Boolean
  - .editDomain(domains, attributes) ⇒ Boolean
  - .deleteDomain(domain) ⇒ Boolean
  - .addDKIM(dkim) ⇒ Boolean
  - .getDKIM(domain) ⇒ Object
  - .deleteDKIM(domain) ⇒ Boolean
  - .addAndGetDKIM(dkim) ⇒ Object
  - .addDomainAdmin(domainAdmin) ⇒ Object
  - .addMailbox(mailbox) ⇒ Object
  - .deleteMailbox(mailboxes) ⇒ Boolean
  - .addAlias(address, goto) ⇒ Boolean
  - .updateMailboxes(mailboxes) ⇒ Array.<MailboxAnswer>
  - .getMailboxes(id) ⇒ Array.<Mailbox>

mailcow-api.MailcowApiClient

Class representing the Mailcow API client

Kind: static class of mailcow-api

.MailcowApiClient
- new module.exports.MailcowApiClient(baseurl, apikey)
- .getDomain([domain]) ⇒ Array
- .addDomain(domain) ⇒ Boolean
- .editDomain(domains, attributes) ⇒ Boolean
- .deleteDomain(domain) ⇒ Boolean
- .addDKIM(dkim) ⇒ Boolean
- .getDKIM(domain) ⇒ Object
- .deleteDKIM(domain) ⇒ Boolean
- .addAndGetDKIM(dkim) ⇒ Object
- .addDomainAdmin(domainAdmin) ⇒ Object
- .addMailbox(mailbox) ⇒ Object
- .deleteMailbox(mailboxes) ⇒ Boolean
- .addAlias(address, goto) ⇒ Boolean
- .updateMailboxes(mailboxes) ⇒ Array.<MailboxAnswer>
- .getMailboxes(id) ⇒ Array.<Mailbox>

new module.exports.MailcowApiClient(baseurl, apikey)

Create a Mailcow API client.

Param	Type	Description
baseurl	`string`	The base url where the api can be found
apikey	`string`	The api key for the mailcow api endpoint

Example

(async () => {
    //get global variables
    require('dotenv').config();
    
    //import the api client module
    const {
        MailcowApiClient
    } = require("mailcow-api")

    //create new mailcow api client with endpoint/baseurl and the api key
    const mcc = new MailcowApiClient(process.env.MAILCOW_API_BASEURL, process.env.MAILCOW_API_KEY);

    //get all domain on mailcow server
    console.log(await mcc.getDomain());
})();

mailcowApiClient.getDomain([domain]) ⇒ `Array`

Gets a specific domain or all domains

Kind: instance method of MailcowApiClient
Returns: Array - Array of domains

Param	Type	Default	Description
[domain]	`String`	`'all'`	The domain you want to get

Example

await mcc.getDomain()

mailcowApiClient.addDomain(domain) ⇒ `Boolean`

Adds a domain to the server

Kind: instance method of MailcowApiClient
Returns: Boolean - True on success

Param	Type	Description
domain	`String` \| `Domain`	The domain you want to add

Example

await mcc.addDomain({
            domain: "example.com",
        }))

mailcowApiClient.editDomain(domains, attributes) ⇒ `Boolean`

Edits one or more domains on the server. Applies the attributes to all domains provided.

Kind: instance method of MailcowApiClient
Returns: Boolean - True on success

Param	Type	Description
domains	`Array` \| `String`	The domains you want to edit
attributes	`Object`	Attributes to change for all domains provided domains

Example

await mcc.editDomain(["example.com"], {
            aliases: 399
        });
        //This will set the aliases of example.com to 399

mailcowApiClient.deleteDomain(domain) ⇒ `Boolean`

Removes a domain from the server

Kind: instance method of MailcowApiClient
Returns: Boolean - True on success

Param	Type	Description
domain	`String` \| `Array`	The domain/domains you want to delete

Example

await mcc.deleteDomain("example.com")

mailcowApiClient.addDKIM(dkim) ⇒ `Boolean`

Generates a DKIM domain key for a domain

Kind: instance method of MailcowApiClient
Returns: Boolean - True on success

Param	Type	Description
dkim	`String` \| `DKIM`	A DKIM object or string

Example

await mcc.addDKIM({
            domain: "example.com",
        })
        //This will generate a DKIM key for example.com on the mailcow server

mailcowApiClient.getDKIM(domain) ⇒ `Object`

Gets the DKIM key for a domain on the mailcow server

Kind: instance method of MailcowApiClient
Returns: Object - The DKIM public key and other parameters

Param	Type	Description
domain	`String`	the domain name you want to get the key for

Example

await mcc.getDKIM('example.com')
        //This will get the DKIM key for the domain example.com from the mailcow server

mailcowApiClient.deleteDKIM(domain) ⇒ `Boolean`

Deletes the DKIM key for a domain on the mailcow server

Kind: instance method of MailcowApiClient
Returns: Boolean - true on success

Param	Type	Description
domain	`Array`	the domain name/names you want to delete the key for

Example

await mcc.deleteDKIM('example.com')
        //This will delete the DKIM key for the domain example.com from the mailcow server

mailcowApiClient.addAndGetDKIM(dkim) ⇒ `Object`

Generates a DKIM domain key for a domain and returns it

Kind: instance method of MailcowApiClient
Returns: Object - DKIM key on success

Param	Type	Description
dkim	`String` \| `DKIM`	A DKIM object or string

Example

await mcc.addAndGetDKIM({
            domain: "example.com",
        })
        //This will generate a DKIM key for example.com on the mailcow server and return it

mailcowApiClient.addDomainAdmin(domainAdmin) ⇒ `Object`

Adds a domain admin to the mailcow server

Kind: instance method of MailcowApiClient
Returns: Object - containing password username and domains on successfull creation

Param	Type	Description
domainAdmin	`DomainAdmin`	a domain admin object that has to contain at least the domains the admin should be able to control

Example

await mcc.addDomainAdmin({
            domains: ['example.com', 'example.org']
        })
        //This will add an admin for the domains example.com and example.org and return their credentials

mailcowApiClient.addMailbox(mailbox) ⇒ `Object`

Adds a mailbox for a domain to the mailcow server

Kind: instance method of MailcowApiClient
Returns: Object - the created mailbox

Param	Type	Description
mailbox	`Mailbox`	a Mailbox object that has to contain at least the domain for which the mailbox shall be created

Example

await mcc.addMailbox({
            domain: 'example.com',
            name: 'Example'
        })
        //This will add a mailbox for the domain example.com and return it

mailcowApiClient.deleteMailbox(mailboxes) ⇒ `Boolean`

Deletes a mailbox

Kind: instance method of MailcowApiClient
Returns: Boolean - true on success

Param	Type	Description
mailboxes	`String` \| `Array`	complete name of the mailbox/mailboxes

Example

await mcc.deleteMailbox("mail@example.com")
        //This will delete the mailbox mail@example.com

mailcowApiClient.addAlias(address, goto) ⇒ `Boolean`

Adds an alias for a mailbox

Kind: instance method of MailcowApiClient
Returns: Boolean - true on success

Param	Type	Description
address	`String`	alias address, for catchall use "@domain.tld"
goto	`String`	destination address, comma separated

Example

await mcc.addAlias("@test.tld","mail@example.com")
        //This will catch all mail for the domain test.tld and put it in the mailbox mail@example.com

mailcowApiClient.updateMailboxes(mailboxes) ⇒ `Array.<MailboxAnswer>`

Updates Mailboxes See the data structure here: https://demo.mailcow.email/api/#/Mailboxes/Update%20mailbox

Kind: instance method of MailcowApiClient

Param	Type	Description
mailboxes	`Array.<Mailbox>`	mailboxes

Example

await mcc.updateMailboxes({
  "attr": {
    "active": "1",
    "force_pw_update": "0",
    "name": "Full name",
    "password": "",
    "password2": "",
    "quota": "3072",
    "sender_acl": [
      "default",
      "info@domain2.tld",
      "domain3.tld",
      "*"
    ],
    "sogo_access": "1"
  },
  "items": [
    "info@domain.tld"
  ]
})

mailcowApiClient.getMailboxes(id) ⇒ `Array.<Mailbox>`

Gets Mailboxes

Kind: instance method of MailcowApiClient

Param	Type	Description
id	`"all"` \| `"user@domain.tld"`	"all" or "user@domain.tld"

Example

const answer=await getMailboxes("all");
     //answer will be: 
     
     [
  {
    "active": "1",
    "attributes": {
      "force_pw_update": "0",
      "mailbox_format": "maildir:",
      "quarantine_notification": "never",
      "sogo_access": "1",
      "tls_enforce_in": "0",
      "tls_enforce_out": "0"
    },
    "domain": "doman3.tld",
    "is_relayed": 0,
    "local_part": "info",
    "max_new_quota": 10737418240,
    "messages": 0,
    "name": "Full name",
    "percent_class": "success",
    "percent_in_use": 0,
    "quota": 3221225472,
    "quota_used": 0,
    "rl": false,
    "spam_aliases": 0,
    "username": "info@doman3.tld"
  }
]

Domain : `Object`

For all options check out https://demo.mailcow.email/api/

Kind: global typedef
Properties

Name	Type	Default	Description
domain	`String`		Name of the domain to add
[active]	`Number`	`1`	Whether the domain should be active or not
[aliases]	`Number`	`400`	Number of aliases allowed
[defquota]	`Number`	`3072`
[mailboxes]	`Number`	`10`
[maxquota]	`Number`	`10240`
[quota]	`Number`	`10240`

Example

{
    active: 1,
    domain: "example.com",
    aliases: 400, // responding "object is not numeric" if missing is this a BUG? should be "aliases missing" if cant be omited anyway
    backupmx: 0,
    defquota: 3072,
    description: "Hello!",
    lang: "en",
    mailboxes: 10,
    maxquota: 10240,
    quota: 10240,
    relay_all_recipients: 0,
    rl_frame: "s",
    rl_value: 10
    }

DKIM : `Object`

Object representing a DKIM Key

Kind: global typedef
Properties

Name	Type	Default	Description
domain	`String`		The domain which a key should be generated for
[dkim_selector]	`String`	`'dkim'`	The dkim selector
[key_size]	`2048` \| `1024`	`2048`	The size of the key

Example

{
  "domain": "example.com",
  "dkim_selector": "dkim",
  "key_size": 2048
 }

DomainAdmin : `Object`

Object representing a domain admin

Kind: global typedef
Properties

Name	Type	Default	Description
domains	`Array` \| `String`		The domains/domain this admin should be able to access
[username]	`String`	`RANDOM`
[password]	`String`	`RANDOM`
[active]	`0` \| `1`	`1`

Example

{
  "active": 1,
  "domains": "example.com",
  "password": "supersecurepw",
  "username": "testadmin"
}

Mailbox : `Object`

Object representing a mailbox

Kind: global typedef
Properties

Name	Type	Default	Description
domain	`String`		domain for wich the mailbox shall be created
[local_part]	`String`	`"mail"`	the local part of the mail address before the @
[name]	`String`	`"John Doe"`	full name of the user
[password]	`String`	`RANDOM`	password for the user. if omitted one will be generated
[quota]	`Number`	`3072`	maximum size of the mailbox
[active]	`0` \| `1`	`1`	whether the mailbox is active or not

Example

{
  "domain": "example.com",
  "local_part": "john.doe",
  "name": "John Doe",
  "password": "paulIstToll",
  "quota": 3072,
  "active": 1
}

mailcow-api-cnc

Mailcow Api

A wrapper for the mailcow web API with the most relevant functions.

Install

Basic Example

What is dotenv?

1. Install the module "dotenv" with

2. Create a file named ".env" in your applications root directory

3. Use your secret variables

Where to get the API key?

1. Open your mailcow UI and login as admin

1.1 Are you using two factor authentication for your admin account?

2. Scroll to and expand the API section

3. Insert the IP you want to accesss the API from or disable the API check

4. Tick the checkbox "Activate API" and save the settings

5. Copy your API key from the field above

Documentation

Need help or missing a feature?

Mailcow API Documentation

Links

Modules

Typedefs

mailcow-api

mailcow-api.MailcowApiClient

new module.exports.MailcowApiClient(baseurl, apikey)

mailcowApiClient.getDomain([domain]) ⇒ Array

mailcowApiClient.addDomain(domain) ⇒ Boolean

mailcowApiClient.editDomain(domains, attributes) ⇒ Boolean

mailcowApiClient.deleteDomain(domain) ⇒ Boolean

mailcowApiClient.addDKIM(dkim) ⇒ Boolean

mailcowApiClient.getDKIM(domain) ⇒ Object

mailcowApiClient.deleteDKIM(domain) ⇒ Boolean

mailcowApiClient.addAndGetDKIM(dkim) ⇒ Object

mailcowApiClient.addDomainAdmin(domainAdmin) ⇒ Object

mailcowApiClient.addMailbox(mailbox) ⇒ Object

mailcowApiClient.deleteMailbox(mailboxes) ⇒ Boolean

mailcowApiClient.addAlias(address, goto) ⇒ Boolean

mailcowApiClient.updateMailboxes(mailboxes) ⇒ Array.<MailboxAnswer>

mailcowApiClient.getMailboxes(id) ⇒ Array.<Mailbox>

Domain : Object

DKIM : Object

DomainAdmin : Object

Mailbox : Object

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

mailcowApiClient.getDomain([domain]) ⇒ `Array`

mailcowApiClient.addDomain(domain) ⇒ `Boolean`

mailcowApiClient.editDomain(domains, attributes) ⇒ `Boolean`

mailcowApiClient.deleteDomain(domain) ⇒ `Boolean`

mailcowApiClient.addDKIM(dkim) ⇒ `Boolean`

mailcowApiClient.getDKIM(domain) ⇒ `Object`

mailcowApiClient.deleteDKIM(domain) ⇒ `Boolean`

mailcowApiClient.addAndGetDKIM(dkim) ⇒ `Object`

mailcowApiClient.addDomainAdmin(domainAdmin) ⇒ `Object`

mailcowApiClient.addMailbox(mailbox) ⇒ `Object`

mailcowApiClient.deleteMailbox(mailboxes) ⇒ `Boolean`

mailcowApiClient.addAlias(address, goto) ⇒ `Boolean`

mailcowApiClient.updateMailboxes(mailboxes) ⇒ `Array.<MailboxAnswer>`

mailcowApiClient.getMailboxes(id) ⇒ `Array.<Mailbox>`

Domain : `Object`

DKIM : `Object`

DomainAdmin : `Object`

Mailbox : `Object`

Weekly Downloads