Moving to Modoboa

You have an existing platform and you’d like to move to Modoboa, the following tools could help you.

Using IMAP protocol

Modoboa provides a way to transfer accounts hosted on a different platform/provider to your personal server using the IMAP protocol and a tool called OfflineIMAP.

It works as follows: * You first declare what needs to be migrated, basically the domain(s) you own and where they can be found. By doing that, you’ll allow accounts hosted on the platform/provider you’re migrating from to log into your Modoboa server * The first time an old account (one coming from your previous provider) successfuly log into Modoboa, a dedicated migration task is created * On a regular basis (every hour generally), a cron job is responsible for generating an OfflineIMAP configuration file including instructions to migrate all declared migrations and lauching OfflineIMAP to start/continue migrations


So, as you probably already understood, you can’t migrate all your accounts at the same time since you probably don’t know their corresponding password. Every account migration must be started by the account’s owner.


Since Modoboa does not handle the installation of OfflineIMAP, you need to do it on your own. The following instructions will help you.

Once done, the new admin interface (v2) will let you: * define the neccessary information to connect to your old platform/provider * define what is to be migrated (ie. the accounts) * customize the behaviour of OfflineIMAP : go to ‘Parameters > Imap Migration’ from the left menu


Auto create domain feature must be enabled to make this feature

work. Go to ‘Parameters > Administration > Mailboxes’ and check if it’s the case.

To generate an OfflineIMAP configuration file, run the following command:

> python generate_offlineimap_config

The synchronization script must be configured to run periodically on your new server. Since it will copy mailboxes content to its final destination, filesystem permissions must be respected. To do that, it must be executed by the user which owns mailboxes (generally vmail).

Here is a configuration example where the script is executed every hours. You can copy it inside the /etc/cron.d/modoboa file:


0       */1     *       *       *       vmail   cd /srv/vmail && $PYTHON $INSTANCE/ generate_offlineimap_config --output .offlineimaprc && /usr/local/bin/offlineimap > /dev/null 2>&1

Feel free to adapt it.

This will sync back-and-forth user mailbox.


A provider represents an IMAP server that hosts one or several domains you own. It includes connection information (network address, port, etc.) and a list of hosted domain.

For each domain you declare, you must provide its name. Modoboa will then create a local domain with the exact same name if needed (ie. if it does not exist yet) the first time it migrates an account.

Optionaly, you have the possibility to rename a domain (for example: -> by providing a value to the ‘Local domain’ field.


Migrations are automatically created, you don’t need to do it.

The first time an account of your old platform successfuly log into Modoboa (using old credentials), a local account and a migration task will be created.


In case of domain renaming as described in Providers, users must use the new email address as username for next connection attempts.

SuperAdmins can monitor running migrations and stop/delete them from the IMAP Migration section (left menu).

From postfixadmin

A dedicated command allows you to convert an existing postfixadmin database to a Modoboa one. Consult the documentation to know more about the process.

Using CSV files

Modoboa allows you to import any object (domain, domain alias, mailbox and alias) using a simple CSV file encoded using UTF8. Each line corresponds to a single object and must respect one of the following format:

domain; <name: string>; <quota: integer>; <default mailbox quota: integer>; <enabled: boolean>
domainalias; <name: string>; <targeted domain: string>; <enabled: boolean>
relaydomain; <name: string>; <target host: string>; <target port: integer>; <service: string>; <enabled: boolean>; <verify recipients: boolean>
account; <loginname: string>; <password: string>; <first name: string>; <last name: string>; <enabled: boolean>; <group: string>; <address: string>; <quota: integer>; [<domain: string>, ...]
alias; <address: string>; <enabled: boolean>; <recipient: string>; ...

Boolean fields accept the following values: true, 1, yes, y (case insensitive). Any other value will be evaluated as false.


The order does matter. Objects are created sequencially so a domain must be created before its mailboxes and aliases and a mailbox must created before its alias(es).

To actually import such a file:

> sudo -u <modoboa_user> -i bash
> source <virtualenv_path>/bin/activate
> cd <modoboa_instance_dir>
> python modo import <your file>

Available options can be listed using the following command:

> python modo import -h