Domains

Overview #

Domain name management is done using the CLI command domain. This command is also employed to administer the DomainKeys Identified Mail (DKIM) settings for each one of your domains. The domain command has the following subcommands:

$ stalwart-cli -u https://jmap.example.org domain

Manage domains

USAGE:
    stalwart-cli --url <URL> domain <SUBCOMMAND>

OPTIONS:
    -h, --help    Print help information

SUBCOMMANDS:
    create     Create a new domain
    delete     Delete an existing domain
    display    Display an existing domain
    help       Print this message or the help of the given subcommand(s)
    list       List all domains
    update     Update an existing domain

Create #

When a new account is created, the CLI tool automatically creates the associated domain name if it is missing. Domain creation can also be done using the domain create subcommand, which accepts the following arguments:

Create a new domain

USAGE:
    stalwart-cli domain create [OPTIONS] <NAME>

ARGS:
    <NAME>    Domain name to create

OPTIONS:
    -c, --cert-dkim <CERT_DKIM>                Path to DKIM private key
    -d, --description <DESCRIPTION>            Description
    -e, --expiration-dkim <EXPIRATION_DKIM>    DKIM expiration (in seconds)
    -h, --help                                 Print help information
    -s, --selector-dkim <SELECTOR_DKIM>        DKIM selector

For example, to create the domain name example.org:

$ stalwart-cli -u https://jmap.example.org domain create example.org

Domain 'example.org' successfully created.

Display #

Domain details are obtained using the domain display subcommand. For example:

$ stalwart-cli -u https://jmap.example.org domain display example.org

+-------------+---------------------------+
| Name        | example.org               |
+-------------+---------------------------+
| Description | Example domain            |
+-------------+---------------------------+
| DKIM        |                           |
+-------------+---------------------------+

List #

Domains are listed using the domain list subcommand. It accepts an optional parameter to filter the domains list by a keyword. For example:

$ stalwart-cli -u https://jmap.example.org domain list

+-------------+-------------+
| Name        | Description |
+-------------+-------------+
| example.org |             |
+-------------+-------------+
| test.org    |             |
+-------------+-------------+


2 records found.

Or using the filter:

$ stalwart-cli -u https://jmap.example.org domain list example

+-------------+-------------+
| Name        | Description |
+-------------+-------------+
| example.org |             |
+-------------+-------------+


1 record found.

Update #

Domain updates are done using the domain update subcommand. It accepts the following arguments:

Update an existing domain

USAGE:
    stalwart-cli domain update [OPTIONS] <NAME>

ARGS:
    <NAME>    Domain name to update

OPTIONS:
    -c, --cert-dkim <CERT_DKIM>                Path to DKIM private key
    -d, --description <DESCRIPTION>            Description
    -e, --expiration-dkim <EXPIRATION_DKIM>    DKIM expiration (in seconds)
    -h, --help                                 Print help information
    -s, --selector-dkim <SELECTOR_DKIM>        DKIM selector

For example, to change a domain’s description:

$ stalwart-cli -u https://jmap.example.org domain update example.org -d "A test domain"

Domain 'example.org' successfully updated.

DKIM #

DKIM (Domain Keys Identified Mail) is an email authentication technique that allows the receiver to check that an email was indeed sent and authorized by the owner of that domain. To ensure email deliverability, it is important that all your domain names have DKIM properly configured.

To enable DKIM on a domain you’ll first need a private key, which can be generated with OpenSSL:

$ openssl genrsa -out dkim_private.pem 2048

This command will create a private key under the dkim_private.pem file name. Using this private key, you can now create the DKIM TXT entry for your DNS server as follows:

$ echo "v=DKIM1; k=rsa; p=`openssl rsa -in dkim_private.pem -pubout -outform der 2>/dev/null | openssl base64 -A`"

Copy the output generated by the above command and add it as a TXT record called [selector]._domainkey.[domain] on your DNS. The selector is a unique identifier you can choose to be associated with your private key, there can be multiple selectors for a same domain. For example, this is how a DKIM DNS record for the domain name example.org using the selector default will look like:

default._domainkey.example.org   TXT    v=DKIM1; k=rsa;  
                p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7uhdIctQbYV88nldTNlhEvUetfSju2
                fxZNkvw7jof8YRLoTueBF3anF3J91NcdNTtflBzgrBnOixalzKsQjJr1hFQKZPsZo1V2en7swd/V
                N2TptKU58SRk2kWNfryEfbyBEdRskWW6yn4CKqf5ianYRezKICbd85uK+wfATOTjeQpgoh7JfJnH
                1zYM2L+haa86KvIytQI4Dh7GD2F04iFAtY/sf4eKRW9vP3EujfOCo6OOjoRVgA//575qE/R14v7+
                qgNgcu7g5OANLFxj+fWLEIVEgNppAAVzKcHDNOt3nX5uzDG2DsKsxxfR1rr8JDwqrHb8qPAKcQKp
                MB3ACWswIDAQAB

The next step is to add the private key to Stalwart JMAP and configure the selector name. This is done with the CLI tool using the account update subcommand. For example, to import the dkim_private.pem key we just created and set the default selector on the domain domain name example.org:

$ stalwart-cli -u https://jmap.example.org domain update example.org \
                            -c dkim_private.pem -s default

Domain 'example.org' successfully updated.

Alternatively, you may also set a DKIM expiration policy in seconds using the -e option:

$ stalwart-cli -u https://jmap.example.org domain update example.org \
                            -c dkim_private.pem -s default -e 86400

Domain 'example.org' successfully updated.

Delete #

Domains are removed using the domain delete subcommand. For example:

$ stalwart-cli -u https://jmap.example.org domain delete [email protected]

Domain '[email protected]' successfully deleted.