mailcow-api

    1.2.6 • Public • Published

    Mailcow Api

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

    npm NPM Snyk Vulnerabilities for npm package Website Website

    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

    Class representing the Mailcow API client

    Kind: static class of mailcow-api

    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

    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
    }

    Install

    npm i mailcow-api

    DownloadsWeekly Downloads

    15

    Version

    1.2.6

    License

    MIT

    Unpacked Size

    37.1 kB

    Total Files

    3

    Last publish

    Collaborators

    • firstdorsal