archiveIMAP copies or moves mail from one account to another. The action is calculated based on the configuration file
archiveIMAP.yaml which must exist in the same directory. The configuration file may contain information on any number of account
pairs, each of which is individually configurable. The script will process them in a random order (they are a Perl hash), but
all accounts which have the enabled flag on will be processed during a given run.

NOTE: the actual configuration file is yaml (archiveIMAP.yaml), but I'm better at Perl structures, so the samples are written
in archiveIMAP.cfg.sample (Perl), then converted to archiveIMAP.yaml.sample using the included utility confToYAML.pl.

Two utilities are provided:

confToYAML.pl - reads a perl structure from stdin, returns the YAML equivilent to stdout
YAMLToconf.pl - Reads the file archiveIMAP.yaml and dumps it to stdout as a perl structure (NOTE, name of hashref should be changed)

The configuration file is broken into two sections, default and accounts. Default values are also included in the script itself.
Order of precedence, from lowest to highest is:

script defaults
default section of configuration file
account section of configuration file

Default selections are:

account is enabled (enabled = 1)
testing is disabled (testing = 0)

For target
   hierarchy = <path> (use original source path on target server)
   server = localhost
For source
   age = 1 year (archive anything older than this). This is the same as 365 and 12M
   delete empty folders is disabled (deleteEmptyFolders = 0)
   delete original message is disabled (deleteOnSuccess = 0
   server = localhost
   system folders = Outbox, Sent Items, INBOX
   ignored folders = Deleted Messages, Drafts, Junk E-mail, Junk, Trash


Again, by simply entering corresponding values into the default section of the configuration file, these values can be overridden.
For example, if your "normal" source server is smtp.example.com and your "normal" target server is archives.example.com, you
can enter those in the default section of the configuration file.

==== hierarchy =====

This is a pattern that will be used to generate the folder names on the target server. It can be any combination of

<path> - the original path on the source server
<year> - the four year part of the Date entry in a particular message header
<month>- the two digit month part of the Date entry in a particular message header
constant - constants will be placed as is. Be careful, there is no checking on that.

The delimiters for the hierarchy is the caret (^) since that seems to be the most innocuous.

To build an archive that has all e-mail separated only by the year and month they were sent, use:
<year>^<month>

If you would like the original tree, but again, with year and month, use
<path>^<year>^<month>

If you would like to put the word "Archives" in there, between the old path and the date/time, you could do
<path>^Archives^<year>^<month>


==== master user ====

dovecot has the ability to be configured with one or more master users 
(see https://doc.dovecot.org/configuration_manual/authentication/master_users/), allowing this script to be run without knowledge
of a users credentials. This has been added as of this version with the addition of the keys
adminUsername
adminPassword
adminSeparator
Which can be placed in the source and/or target, and either in the default or individual accounts.