API

Integration into your own Systems is extremly simple. So simple that all you might need to do is place one JSON File on a web server.

Depending on your use case you have the choice between two different APIs:

Basic JSON API

With the Basic JSON API you provide your account and alias configuration via HTTPS. The controller will regularly fetch the configuration file.

Structure

The JSON document has a key for each domain that contains an object. Each domain-object can have the keys "account" and "alias" that contain the respective lists of objects.

Each account object has a "name" which is the part before the @ below the domain and a hashed password.

Each alias object also has a "name" in the same style as an account. In the "to" field one or more comma-seperated recipients can be specified.

Example

{
    "example.com": {
        "account": [
            {
                "name": "alice",
                "password": "$1$9hW1N3SC$J6vfo890zc50GC1jYHP211"
            },
            {
                "name": "bob",
                "password": "$1$0MhHZVnG$d6rHD1KFLNOJ9EFdMKrB91"
            }
        ],
        "alias": [
            {
                "name": "office",
                "to": "alice@example.com,bob@example.com"
            }
        ]
    }
}

This creates two email accounts for alice@example.com and bob@example.com. It also creates an email alias office@example.com that forwards mail to both mailboxes.

For formatting reasons short hashes have been used in this example but more secure variants like "$6$rounds=100000$vE8/iTZi9/cC/RCk$lkjkaN9LY3KAiF0lxmd/dfvkxKm9WDnyG.onOaXCJ64htjzkpzxRCNLZFDbi5ggwTf4Z3vbo3pPATJzgtytU//" are also supported.

REST JSON API

The REST API gives you more fine grained controll over the system. Updates propagate faster (within seconds usually) then with the basic JSON API. All requests have to use HTTPS and be directed to the Controller.

Accounts

Model structure:

Account {
    id (string),
    name (string),
    domain (string),
    password (string),
    spoofing_whitelist (string),
    submission_disabled (boolean)
}

The id field contains the complete email address which consists of the name@domain. The password can be read only in hashed form and written in plain text.

POST /mail/account/

Parameters:

  • name
  • domain
  • password
  • submission_disabled (optional, default = False)
  • spoofing_whitelist (optional, default = '')

GET /mail/account/

Returns a list of accounts.

Parameters:

  • domain (optional, default = all domains)

GET /mail/account/{id}/

Returns account.

POST /mail/account/{id}/set_password/

Sets a new password.

Parameters:

  • password

DELETE /mail/account/{id}/

Deletes the account.

POST /mail/account/{id}/disable_submission/

Disables sending from this account. Emails can still be received.

POST /mail/account/{id}/enable_submission/

Enable sending of Emails from this account.

POST /mail/account/{id}/set_spoofing_whitelist/

Parameters:

  • spoofing_whitelist

The spoofing whitelist is a comma seperated list of addresses and domains the user can use as From when sending email, in addition to its own. The default is empty which only permits sending from the own mail-address. In addition to specific addresses and domains the whitelist can also be set to the wildcard '*' to permit all addresses.

Example:

The user alice@example.com with the whitelist 'office@example.com,skylime.net' can send from the following addresses:

  • alice@example.com
  • office@example.com
  • someone@skylime.net

But not:

  • bob@example.com
  • anyone@frubar.net

Alias

Model Structure

Alias {
    id (string, optional)
    name (string),
    domain (string),
    to (string),
}

The id field contains the complete email address which consists of the name@domain. The to field can contain one or more comma seperated email addresses that should receive emails sent to this alias.

POST /mail/alias/

Create new alias.

Parameters:

  • name
  • domain
  • to

GET /mail/alias/

Returns list of aliases.

Parameters:

  • domain (optional, default = all domains)

GET /mail/alias/{id}/

Returns alias.

PUT /mail/alias/{id}/

Update list of recipients.

Parameters:

  • to

DELETE /mail/alias/{id}/

Delete this alias.