iRedUtils: CLI and REST API for iRedMail

Purpose

iRedMail is a great mailserver appliance - I would even go as far and say it's the best out there. I have been using it for 5+ years. However, I really prefer the clean and quick way to use a CLI to manage my servers instead of relying on a web interface. Also, I was missing an open REST API to create and modify mailboxes.

For this purpose I created a simple set of utilities consisting of a CLI tool called iredcli as well as a REST API to integrate external services. It certainly does not cover the full stack of the iRedAdmin Pro interface, but for me it gets the job done.

Installation

• Install iRedMail
  • see instructions on www.iredmail.org
• Install Git:
  • apt-get install git
• Clone the repository into /opt/iredutils/:
  • cd /opt
  • git clone https://github.com/zeyosinc/iredutils.git
• Install the composer dependencies through composer
  • cd /opt/iredutils/
  • curl -sS https://getcomposer.org/installer | php
  • php composer.phar install
• Create a config.php file and include your database settings
  • cp config.template.php config.php
  • Edit the file and include the database settings for the vmailadmin user
  • You can find those settings in the iRedMail.tips file generated by the iRedMail installer
• Create an alias for the iredcli command
  • ln -s /opt/iredutils/iredcli /usr/bin/iredcli

That's it! You can now us the CLI through the iredcli command and access the REST API. Have fun!

In case you want to use the REST API, you need to perform some additional steps:

a. Create an Apache configuration file in /etc/apache2/conf-available/iredutilsapi.conf:

<Directory /opt/iredutils>
    DirectoryIndex api.php
    Require all granted
</Directory>

Make sure you replace Require all granted with the appropriate security settings. (see https://httpd.apache.org/docs/2.4/howto/access.html).

b. Next, enable the configuration by typing a2enconf iredutilsapi.

c. After this, edit the SSL site settings by opening the file /etc/apache2/sites-enabled/default-ssl.conf:

RewriteEngine on
RewriteRule ^/api/?(.*) /opt/iredutils/api.php/$1

d. Before restarting the web server, make sure that mod_rewrite is enabled: a2enmod rewrite.

e. Now, restart your webserver by typing service apache2 restart

REST Endpoints

GET: /domain

List domains

POST: /domain/:domainname

Creates a new domain

CLI Usage

Domains

iredcli domain
  show
  add <DOMAIN>
  remove <DOMAIN>
  export
  import <FILENAME>

Mailbox

iredcli mailbox
  show [<DOMAIN> --search=<SEARCH>]
  add <EMAIL> [--password=<PASSWORD> --maildir=<MAILDIR>]
  update <EMAIL> [--password=<PASSWORD>]
  remove <EMAIL>
  export [<DOMAIN> --search=<SEARCH>]
  import <FILENAME>

Alias

iredcli alias
  show [<DOMAIN|EMAIL> --search=<SEARCH>]
  add <ALIAS> <MAILBOX>
  remove <ALIAS> [<MAILBOX>]
  export [<DOMAIN|EMAIL> --search=<SEARCH>]
  import <FILENAME>

Alias

iredcli policy
  show [<POLICYGROUP> --search=<SEARCH>]
  add <POLICYGROUP> <MEMBER>
  remove <POLICYGROUP> <MEMBER>
  learn <ham|spam|forget> <FILE>

Importing data

You can import data through JSON. The JSON format for each individual endpoint is as follows:

Domains

[
  {
    "domain": "acme.com"
  },
  ...
]

Alternative:

[
  "acme.com",
  ...
]

Mailbox

[
  {
    "username": "mailbox1@acme.com",
    "password": "xxx",
    "maildir": "acme.com/m/a/i/..."
  },
  ...
]

maildir is an optional parameter. If not supplied, a directory will be created. Instead of password you can also supply a parameter called hash with the hashed password instead.

Alias

[
  {
    "address": "alias@alias.com",
    "goto": "mailbox1@acme.com,mailbox2@acme.com"
  },
  ...
]

Examples

./iredcli domain add test.com
./iredcli mailbox add demo@test.com
./iredcli mailbox add test@test.com
./iredcli mailbox add helo@test.com
./iredcli alias add alias2@test.com test@test.com
./iredcli alias add alias@test.com test@test.com
./iredcli alias add alias@test.com demo@test.com
./iredcli alias show
./iredcli mailbox show
./iredcli alias remove alias@test.com demo@test.com
./iredcli alias show
./iredcli mailbox remove test@test.com
./iredcli domain remove test.com
./iredcli mailbox remove test.com --search=.

Contributing

Please note that this is a side project for me and was mainly created to "skratch my own itch", so I only maintain it to the degree that I require it to work for my purposes. If you find any bugs of you have ideas for new features, be a sweatheart and simply send me a pull request. Cheers!

License

Copyright (C) 2015 Peter Haider

This work is licensed under the GNU Lesser General Public License (LGPL) which should be included with this software. You may also get a copy of the GNU Lesser General Public License from http://www.gnu.org/licenses/lgpl.txt.