====== offlineimap3 IMAP syncronization: nametrans ======

In this page we study a case of IMAP syncronization from a source IMAP server to a Maildir structure on local disk, using the **[[https://github.com/OfflineIMAP/offlineimap3|offlineimap3]]** tool.

The main issue is the need to **map the source directory tree** into a tree compatible with the receiving Maildir hierarchy. Here are the issues:

The **source IMAP** server has the following characteristics:

  * The directory separator is the "/" character.
  * Some subfolders are stored into the INBOX, but others are stored at the top level.
  * Some subfolders have names containing the "." character.

The **destination Maildir** has the following characteristics:

  * The directory separator is the "." character.
  * All the subfolders must be under the INBOX.
  * The "." character is not allowed in folder names.

In this case we need a very special **nametrans** expression into the [[https://github.com/OfflineIMAP/offlineimap3|offlineimap3 configuration file]].

:!: **NOTICE**: The mapping of the top-level folders under the INBOX during the transfer from IMAP to Maildir prevents the reverse mapping from Maildir to IMAP, therefore only synchronization from IMAP to Maildir will be possible and not vice versa.

===== Testing the nametrans option =====

It is possibile to write a simple Python script to test the **nametrans** expression:

<code python>
#!/usr/bin/env python3
import re

# From IMAP to Maildir:
# Add a leading '.' to the folder name.
# Remove the leading INBOX folder name.
# Move the top-level folders into the INOBOX.
# Replace the '.' character with the '_' in folder names.
nametrans = lambda foldername: re.sub(
        r'^\.INBOX$', '',
        '.' + re.sub(
            r'^INBOX/', '',
            foldername.replace('.', '_')
        )
)

dirs = [
    'INBOX',
    'INBOX/XFER NETWORK',
    'INBOX/general management',
    'Archives',
    'Archives/2013',
    'INBOX/M.T.T.',
    'INBOX/NEW OFFICES '
]

for name in dirs:
    print('%-30s => "%s"' % ('"' + name + '"', nametrans(name)))
</code>

Running the script you can verify that directories from the source IMAP server will be mapped to the local Maildir:

<file>
"INBOX"                        => ""
"INBOX/XFER NETWORK"           => ".XFER NETWORK"
"INBOX/general management"     => ".general management"
"Archives"                     => ".Archives"
"Archives/2013"                => ".Archives/2013"
"INBOX/M.T.T."                 => ".M_T_T_"
"INBOX/NEW OFFICES "           => ".NEW OFFICES "
</file>

:!: **NOTICE**: The translated name of a sub-subfolder contains the original **directory separator** (.e.g. ''.Archives/2013''), this is OK because offlineimap3 is aware of the differencies in directory separator from the IMAP surce (the "/" is detected automatically) and the destination Mailird ("." is the default). So the destination folder is correctly created as ''.Archives.2013''.

===== The configuration file =====

This is the overall **offlineimap.conf** file:

<file>
[general]
accounts = CopyFromIMAP

[Account CopyFromIMAP]
remoterepository = OldServer
localrepository = NewServer

[Repository OldServer]
type = IMAP
nametrans = lambda foldername: re.sub(r'^\.INBOX$', '', '.' + re.sub(r'^INBOX/', '', foldername.replace('.', '_')))
remotehost = mail.oldserver.com
remoteuser = username@oldserver.com
remotepass = MySecret
createfolders = False

[Repository NewServer]
type = Maildir
localfolders = /home/username/Maildir
</file>

Notice the ''createfolders = False'' for the source IMAP server. As explained above the syncronization is uni-directional from IMAP to Maildir, so we avoid to propagate directories backward.

To run the command with some debugging:

<code>
offlineimap -1 -c ./offlineimap.conf -d imap,maildir -l offlineimap.log
</code>

===== Web References =====

  * **[[https://github.com/OfflineIMAP/offlineimap3/blob/master/offlineimap.conf|offlineimap.conf]]**