IMAP Tools

IMAP Tools

imapcopy is a utility for copying a user's messages from one IMAP server to another.   
It logs into one server with your username & password, builds a list of your 
mailboxes and the messages in them, then logs into the other server with your 
username/password on that machine and copies the mailboxes and messages to it.  
The mailbox (folder) structure is reproduced on the other server.  The IMAP status 
flags are preserved (eg SEEN, DELETED, etc) along with the dates on the original messages.
                                                                     
Usage:  imapcopy.pl -S host1/user1/password1 -D host2/user2/password2    

Optional arguments:                                               
   -d debug                                                      
   -v verbose (displays the progress of copying process)
   -I show IMAP protocol exchanges
   -L logfile                                                    
   -m <mailbox list> (copy only certain mailboxes, eg "INBOX,Drafts,etc")
   -R include submailboxes when used with -m
   -e <mailbox list> (exclude the listed mailboxes, eg "Trash,Wastebasket,etc")
   -g <mailbox list> (exclude the listed mailboxes using regular expressions)
   -r clears the Deleted flag from copied messages
   -x <delimiter [prefix]> Specify the src mbx delimiter and prefix (if server does not support NAMESPACE command)
   -y <delimiter [prefix]> Specify the dst mbx delimiter and prefix (if server does not support NAMESPACE command)
   -p <root mailbox> (put copied mailboxes under a root mailbox)
   -M <file of mailbox name mappings>
   -X <max size in MB>  Maximum message size to be copied 
   -U update mode.  Only copy messages that do not already exist on the destination.
   -s In update mode delete messages from the destination which don't exist on the source
   -B <msgnum start> Start copying messages from this number on.
   -E <msgnum end> Stop copying messages after this one.
   -a <DD-MMM-YYYY> Copy only those messages after the specifed date.
   -b <DD-MMM-YYYY> Copy only those messages before the specifed date.
   -u Skip unread messages, copy only the read ones.
   -H Copy only message headers
   -z Don't require messages to have a Message-ID in the header
   -G source is Gmail, strip '[Gmail]' from mailbox names
   -f In update mode remove messages from the source which exist on the destination

You can select a port number other than the standard IMAP port (143) by 
specifying the host value as host:port, eg localhost:993.

The -M argument allows you to change the names of mailboxes as they are 
copied from the source to the destination system.  To do so, create a file of
names in the format of "<source mailbox>: <destination mailbox>." For 
example:

Inbox: Migrated_inbox
OldMail/2007/documents: OldMail/07/documents
Sales: Old/sales/notes 

Please note that when using the -M option if any mailbox names contain non-ASCII 
characters you must install the Perl Encode::IMAPUTF7 module.  The IMAP standard 
requires that such mailbox names be encoded in the Modified UTF-7 character set.

Administrator access.
imapcopy supports AUTHENTICATION=PLAIN login.  One advantage that 
provides is that you don't have to supply the user's password, just the name
and password of an administrator's account which is authorized to assume a user's
identify. This is particularily useful when doing mass migrations.  

The syntax is -S host/user:admin/admin_password.

Note that not all servers support AUTHENTICATION = PLAIN and of those that do some 
support it only over a secure connection (eg SSL).

Web browser mode
In addition to command-line mode imapcopy can also be used from a Web browser.  Please
see the IMAP Tools User Guide (Section 8) for details on how to install, configure,
and use imapcopy as a Web browser application.

pop3toimap.pl is a tool for copying a user's messages from a POP3  
server to an IMAP4 server.  pop3toimap.pl makes a POP3 connection  
to the POP3 host and logs in with the user's name and password.    
It makes an IMAP connection to the IMAP host and logs in with the  
user's IMAP username and password.  pop3toimap.pl then fetches     
each message from the user's POP3 account and copies it to the     
user's IMAP account.                                               
                                                                   
The usernames and passwords are supplied via a text file specified 
by the -i argument.  The format of the file of users is:           

popUsername password imapUsername password    

Usage: pop3toimap.pl -p POP3host -i IMAPhost -u input_file

Optional arguments:
    -A <admin_user:admin_password>
    -n notify e-mail address
    -r delete POP3 message after copying to IMAP
    -t timeout in seconds
    -m <mailbox>  Default INBOX.  Specify as mbx1/mbx2/mbx3.
    -d debug mode
    -I show IMAP protocol exchanges
    -L logfile
    -R <range of messages, eg 200-333, to copy>
    -h print this message

You can also process a single user without using a file of users.  Just 
specify the credentials on the command line using the -i and -p arguments
as shown below:

     -p pophost[:port]/popuser/poppwd -i imaphost[:port]/imapuser/imappwd

imapdump.pl will copy messages from an IMAP server and place them under
a directory the value of which you supply with the -f argument.  The
name of each file is the message number associated with it in the IMAP
server message store.  When the script finishes the file structure will
look something like this:

 /tmp/mailboxes/INBOX
      1 2 3 4 5 .....
 /tmp/mailboxes/drafts/
      1 2
 /tmp/mailboxes/save/2002
      1 2 3 4 5 6 7 8 9 a b c d e f 10 11 ...
 /tmp/mailboxes/save/2003
 etc 

Usage: imapdump.pl  -f /tmp/mailboxes  -S localhost/user/mypassword

Optional arguments are:
  -l <file of users>
  -n <number of simultaneous processes to run>
  -A <admin_user:admin_password>
  -x <extension>.  Dump files are given this extension (eg -x EML  ==> 1.EML)
  -F <flags> where flags is a comma-separated list of either 
  standard or custom IMAP flags.  Messages with flags matching any 
  values in the list will dumped.
  -d debug
  -L <logfile>
  -m <mailbox list>  For example "INBOX,drafts,save/2003" will copy only the
messages in the indicated folders.
  -a <DD-MMM-YYYY>  Dump only the messages which arrived after this date
  -e exclude mailbox list (using exact matches)
  -E exclude mailbox list (using regular expressions)
  -s Mark SEEN messages by appending ',S' to message filename (dumptoIMAP will flag them as SEEN)
  -g Extract attachments as separate files.  Use with -x EML argument.
  -z Include all status flags in message filename (2454,DSF or 2454,SA
  -C Include custom (nonstandard) flags in message filename, eg 298,$SPECIAL$
  -w Update the msg file status flags when they change on the server

dumptoIMAP.pl is a companion script to imapdump.  It will take a set of messages
extracted from an IMAP server by imapdump (or some other utility which uses the 
same format) and will load them into a mailbox on an IMAP server.

./dumptoIMAP.pl                     \
     -i host/username/password      \
     -L dumptoIMAP.log              \
     -D /work/dump/Inbox            \
     [-m mbx1,mbx2,...,mbx3]
     [-A admin_user:admin_password]

The -D argument points to the directory where the message files are located.
This directory should not have any files other than the messages.  The optional -m
argument can be used to limit the mailboxes to be loaded rather than 
to the list supplied rather than loading all of them.

imapfilter allows you to scan folders on an IMAP server and move selected
messages to different folders based on the contents of designated
message header fields, eg Subject, From, Date, etc.

imapfilter also supports the use of regular expressions in the
matching rules.  For instance, the following rule will move
all messages from a sender named "Jack" from the inbox to
the wastebasket.

From     ^Jack*   Inbox  Wastebasket

Some examples of filter rules:

#  Header field  match  source-mailbox   destination-mailbox.
#  Note that mailboxes are case-sensitive but filter criteria are not.

Subject  test$   Inbox Junk
Importance High junk Inbox
From  *abc.com Inbox Wastebasket
X-Priority 3 Inbox Wastebasket
Size  >50000 Inbox Big_Messages

Usage: imapfilter -S host/rfs/mypassword -r rules.dat -L imapfilter.log
         Optional argument:  -E <admin_user:admin_password>

Optionally the destination mailbox can belong to another user on the local server
or on a remote IMAP server.  In the following two examples the first rule moves
messages to a local mailbox belonging to another user while the second moves
messages to a remote IMAP server.

Subject *home*     INBOX  localhost:INBOX 
Subject *testing*  INBOX  remotehost.xyz.com:INBOX

Access control info must be supplied in the rules file as shown below.  Note that
you can specify the IMAP port of the remote server if it is different than the
standard 143.

RemoteServer: localhost/user1/password1
RemoteServer: remotehost.xyz.com/user2/password2
RemoteServer: remote.acme.com:1430/user2/password2

Wild-card mailboxes.  You can specify a '*' character in place of the local
mailbox name in a rule.  This causes imapfilter to search the messages in each mailbox
for matches.  For example:

Subject *sales*     *   filtered_messages

Notes on Date comparision operations.  imapfilter permits you     
to filter on dates which are earlier, later, or the same as a    
specified date.  The date in the rules must be in RFC822 Mail   
date format (eg, >12 Nov 2009 12:45:10 +0500 means messages whose
date is more recent that 12 Nov 2009 12:45:10 +0500) or expressed as an  
offset from the current date (eg >30 meaning within the past 30  
days and <30 meaning more than 30 days old).  Some examples:                                            
                                                                  
  Date    ">22 Dec 2008 15:00:00 +0000"      INBOX   MOVED      
  Date    "<15 Jan 2009 00:00:00 +0500"      INBOX   MOVED      
  Date    "=25 Dec 2009 08:00:00 +0500"      INBOX   MOVED      
  Date    ">60"  INBOX   OLD                                 
  Date    "*2009*"  INBOX   2009_messages                              

Also please note that in order to use the date comparison feature you must install
the DateTime, DateTime::Format::Mail and DateTime::Format::DateParse Perl
modules.

The -f argument ("first match") causes imapfilter to honor the first rule that matches
and to ignore any subsequent matches.  Without -f the last matching rule is the
one that gets applied.

Administrator access.
imapfilter supports AUTHENTICATION=PLAIN login.  One advantage that
provides is that you don't have to supply the user's password, just the name
and password of an administrator's account which is authorized to assume a user's
identify. This is particularily useful when doing mass migrations.

Use the -E argument to supply the admin username and password:  -E admin_user:admin_password

Multi-user mode

If you want imapfilter to apply the rules to a list of users then you can do
that by supplying the list with the -u  argument as shown below:

  -u <file of users>  Format user:password

IMAP SEARCH Syntax

Support for IMAP SEARCH syntax was introduced in version 1.41 of imapfilter.

IMAP SEARCH provides a way to execute more sophisticated searches than was possible 
in previous versions which were restricted to a single keyword/value search like 
'Subject "Test Message"'.

For example:

OR (FROM george) (FROM sam) (FROM linda)
OR (SUBJECT Invoices) (TO someone@gmail.com)
NOT (TO john.smith)

When the prefix operator is omitted AND is implied:

(SUBJECT sanders) (SUBJECT guide)
(FROM test) (FROM george) (FROM smith)
(FROM john) (TO tom)
(SINCE 01-JAN-2014)(BEFORE 31-JAN-2014)

A number of other keywords and operators are available such as ones that work on 
dates like SENTSINCE, SENTBEFORE, SENTON.

Note on SINCE and BEFORE expression.  In addition to fixed dates you can specify
the date as a number-of-days" offset.  For instance, to create a rule that is
applied to messages older than 30 days you could write (BEFORE 30).  imapfilter will
interpret the value as TODAY - 30 days so if today is 28-JUL-2014 then a value of
30 will result in a date of 28-JUN-2014.

To use the IMAP SEARCH syntax you must include the keyword ISEARCH as the first 
term in a rule.  (This informs imapfilter that IMAP SEARCH syntax is being used) 
instead of the traditional imapfilter rule syntax.  For instance:

ISEARCH "(from rick) (subject guide)" INBOX SEARCH_RESULTS

You can include a mix of IMAP SEARCH and traditional searches in the rules file:

Subject  "\[imap-tools\]\s*Fixed bug"    Trash   INBOX
Subject  "requires approval"     INBOX   Trash
ISEARCH  "(SUBJECT sanders) (SUBJECT guide)" INBOX OLD-DOCS
ISEARCH  "(FROM test) (FROM george) (FROM smith)" INBOX S***ED_MSGS

*************************************************************************
Note that the IMAP SEARCH function does not support regular expressions.   
*************************************************************************   

Please refer to RFC3501 Section 9 ("Formal Syntax") for the rules on composing 
a valid IMAP SEARCH.  Following is an excerpt from the RFC.

search          = "SEARCH" [SP "CHARSET" SP astring] 1*(SP search-key)
                    ; CHARSET argument to MUST be registered with IANA

search-key      = "ALL" / "ANSWERED" / "BCC" SP astring /
                  "BEFORE" SP date / "BODY" SP astring /
                  "CC" SP astring / "DELETED" / "FLAGGED" /
                  "FROM" SP astring / "KEYWORD" SP flag-keyword /
                  "NEW" / "OLD" / "ON" SP date / "RECENT" / "SEEN" /
                  "SINCE" SP date / "SUBJECT" SP astring /
                  "TEXT" SP astring / "TO" SP astring /
                  "UNANSWERED" / "UNDELETED" / "UNFLAGGED" /
                  "UNKEYWORD" SP flag-keyword / "UNSEEN" /
                    ; Above this line were in [IMAP2]
                  "DRAFT" / "HEADER" SP header-fld-name SP astring /
                  "LARGER" SP number / "NOT" SP search-key /
                  "OR" SP search-key SP search-key /
                  "SENTBEFORE" SP date / "SENTON" SP date /
                  "SENTSINCE" SP date / "SMALLER" SP number /
                  "UID" SP sequence-set / "UNDRAFT" / sequence-set /
                  "(" search-key *(SP search-key) ")"

If your search criteria does not comply with the syntax you'll get an error like 
this one and the rule will be ignored.

BAD command syntax error: NOT (XXXXTO jay.anderson)

Optionally you can run imapfilter in dry-run ("test") mode where it tells you what
would have been done but doesn't actually do anything.  Set -t to do a dry-run.

imapPing is a tool for getting a rough feel for the response times
from an IMAP server.  It connects to the server and then performs
some basic IMAP operations on a user's  account and displays the
time as each one is executed.  The operations are:

  1.  Connect to the IMAP server
  2.  Log in with a username and password
  3.  Get a list of mailboxes
  4.  Select the INBOX
  5.  Get a list of messages in the INBOX
  6.  Log off the server

Usage: imapPing.pl -h imap.server.com -u rfs9999 -p XXXXX
    Optional argument:  -A <admin_user:admin_password>

imapsync is a tool for synchronizing user accounts on a pair of
IMAP servers called the "source" and "destination" hosts.   
You supply it with the host/userid/password on each host (and 
optionally a list of mailboxes).  imapsync does the following:
 
1.  Adds any messages on the 1st host which aren't on the 2nd 
2.  Deletes any messages from the 2nd which aren't on the 1st 
3.  Sets the message flags on the 2nd to match the 1st's flags

imapsync works like this:

1.  Log into the source host using the user name and password
2.  Get a list of all mailboxes belonging to the user and a 
    list of messages in each mailbox.
3.  Do the same for the destination host
4.  For each message on the source see if the message exists on 
    the destination.  If not, add it to the destination.
5.  For each message on the destination see if the message exists 
    on the source.  If not, delete it from the destination (eg, 
    set the \Deleted flag and expunge the mailbox).
6.  For each message on the source compare the message flags with 
    the message flags on the destination.  If they don't match 
    update the flags on the destination.
 
Some notes:
 
a.  By default all of the user's mailboxes are processed but you 
    can limit that by providing a list of mailboxes in which case 
    only those will be examined (eg -m "Inbox, Drafts, Actions").
 
b.  The Message-Id is used for identifying messages in an IMAP account.  
    A consequence of this is that if you have multiple copies of a 
    message in a source mailbox only one copy will be reproduced on 
    the destination host.
 
Usage: imapsync -S sourcehost/username/password -D desthost/username/password
       imapsync -S sourcehost -D desthost -u <users file>
 
Other (optional) arguments are:
 
  -L logfile  (if omitted the output goes to STDOUT)
  -u <file of users>  Format srcUser:srcPwd:dstUser:dstPwd
  -d debug mode
  -m mailbox list (eg "Inbox, Drafts, Actions")
  -x <delimiter [prefix]> Specify the src mbx delimiter and prefix (if server does not support NAMESPACE command)
  -y <delimiter [prefix]> Specify the dst mbx delimiter and prefix (if server does not support NAMESPACE command)
  -n Do not delete messages from the destination that do not exist on the source
  -E  source admin user and password
  -F  destination admin user and password
  -q Quiet mode.  Print less details on STDOUT but log everything to the logfile
  -R Compress multiple embedded spaces in mbx names down to one (Gmail doesn't like multiple spaces)
  -t Test mode.  Do a dry-run showing what would have been done but don't actually do anything

Admin mode:  To activate admin mode where you use an admin user and password instead
             of the user's password, set the -E argument for a source user (-F for a
             destination user) and leave the user's password blank.  See Admin login 
             for details.

IMAPtoMbox will copy mailboxes and messages from an IMAP server to the local
server (or PC) in the Unix mbox format.  The mailbox hierarchy (nested mailboxes)
is preserved.
 
To run IMAPtoMbox you supply the name of the IMAP server, your username & password 
along with a pointer to the directory on the local host where the mailboxes are to be 
created.  The local mailbox is given the same name as the IMAP mailbox.  For example:
 
Usage: IMAPtoMbox -i server/user/pwd -m mailbox_directory

Optional arguments:
 
-L logfile

For example:
./IMAPtoMbox                                      \
        -i mail.abc.com/rick.sanders/mypassword   \
        -m  /home/rfs                             \
        -L IMAPtoMbox.log
        [-A <admin_user:admin_password>]
 
The -i argument supplies the imap server name / the username / user's password.    
See the usage() notes for additional arguments, such as -M to copy only certain IMAP 
mailboxes, -d to turn on debugging output and -o user to set the ownership of 
the mailbox files. When used with -M the -r argument will copy all submailboxes
of the ones in the mailbox list.

imap_to_maildir.pl can be used to copy the messages in an IMAP account to
a user's Maildir.

Usage: imap_to_maildir.pl -S IMAPHost/User/Password -u <user> -M <maildir>

For example:  ./imap_to_maildir.pl -S localhost/rich/pwd -u rick -M /users/rick/Maildir

Optional arguments:
     -A <admin_user:admin_password>
     -d debug
     -I log IMAP commands
     -L logfile
     -m mailbox list (eg "Inbox,Drafts,Notes". Default is all mailboxes)
     -a <DD-MMM-YYYY> copy only messages after this date

maildir_to_imap.pl can be used to copy the messages in a maildir to IMAP               
mailboxes. 

Usage: maildir_to_imap.pl -i <users list> -D <imapHost[:port]> 

Each line in the user list must contain a pointer to the user's maildir, 
his IMAP username, and his IMAP password with the values separated by 
commas.  For example:

#  Format:  maildir,IMAP user,IMAP password
/mhub4/maildirs/jsampson@abc.net,jessi.sampson,secret
/mhub4/maildirs/rsmith@abc.net,rick.smith,wouldntyouliketoknow
/mhub4/maildirs/jjones@abc.net,jane.jones,nip123

Optional arguments:

-A <admin_user:admin_password>
-L logfile
-n <integer>  (The number of child processes to run, default is 1)
-d debug
-I log IMAP protocol messages

MboxtoIMAP.pl is used to copy the contents of Unix mailfiles to IMAP               
mailboxes.  It parses the mailfiles into separate messages which are 
inserted into the corresponding IMAP mailbox.           

Usage: MbxtoIMAP.pl -m mailfiles -i server/user/pwd

Optional arguments:

-m <directory>  directory holding a set of mailfiles
-f <mailfile> full filespec of individual mailfile
-n <name of IMAP mailbox> Used with -f argument
-U Update mode, don't copy messages if they already exist
-A <admin_user:admin_password>
-L logfile
-d debug
-r <range of messages to copy>  for example, 1-500 or 25-75
-R remove messages from mailfile after copying to the IMAP server

mbxIMAPsync is used to synchronize the contents of a Unix      
mailfile with an IMAP mailbox.  The user supplies the location   
& name of the Unix mailbox (eg /var/mail/rfs) and the hostname,   
username, & password of the IMAP account along with the name      
of the IMAP mailbox.  For example:                                
                                                                     
Usage:  mbxIMAPsync.pl -f /var/mail/rfs -i imapsrv/rfs/mypass -m INBOX  
                                                                     
mbxIMAPsync compares the messages in the mailfile with those in   
the IMAP mailbox by Message-Id and adds the ones in the mailfile  
which are not in the IMAP mailbox.  Then it looks for messages    
in the IMAP mailbox which are not in the mailfile and removes     
them from the IMAP mailbox.

This script deletes all of the messages in a user's IMAP          
mailbox.                                                          
                                                                  
purgeMbx.pl is called like this:                                  
    ./purgeMbx.pl -s host/user/password -m mailbox               
                                                                  
Note that the mailbox name is case-sensitive.                     
                                                                  
Optional arguments:                                               
    -d debug                                                      
    -L logfile       
    -A <admin_user:admin_password>

trash.pl opens a connection to an IMAP server, logs in with 
a username and password, searches mailboxes for messages marked 
for deletion, and moves them to the trash folder.  The name of
the trash folder is supplied with the -t argument.
 
For example:

Usage: trash.pl -S server/user/pwd -t "Wastebasket"

Optional arguments:

-i <user list> (file of users and passwords, format "user password")
-a <admin_user:admin_password>
-m mailbox_list (eg "Inbox, Drafts, Notes". Default is all mailboxes)
-e  empty the trash can
-L  logfile
-d debug
     
For example:

    trash.pl starting
    Checking mailboxes for deleted messages...
       Moved 2 messages from Drafts to Wastebasket
       Moved 4 messages from Sent Items to Wastebasket
       Moved 45 messages from INBOX to Wastebasket
     
    51 messages were moved to Wastebasket
    The Wastebasket mailbox has been emptied

thunderbird_to_imap is a tool for copying the folders and messages in them
from Thunderbird to an IMAP server.  You supply it with the name of the IMAP
server along with your username and password.  The -m argument is
used to indicate the root directory where the Thunderbird mailfiles
reside.  For example:

"/DOCUMENTS AND SETTINGS/RICK/APPLICATION DATA/Thunderbird/Profiles/default/dlss3fw9.slt/Mail/mail.earthlink.net"

Usage: thundebird_to_imap.pl -i host/username/password -m <thunderbird root>

Optional arguments:

-L logfile
-d debug mode 
-U update mode, copy only messages that do not already exist in IMAP
-M <folder list>, eg folder1,folder2,etc.  Copy only these folders
-A <admin_user:admin_password>
-I show IMAP commands and responses

Note:  It is a good idea to compact your Thunderbird folders prior to running
thunderbird_to_imap.

delIMAPdups looks for duplicate IMAP messages in a mailbox by    
finding messages in each mailbox that have the same Message   
ID.  When a duplicate message is found the DELETED flag is set.  
If the -p argument has been supplied then an EXPUNGE operation   
is executed on the mailbox in which the message resides to remove
it.
                                                                 
Note that delIMAPdups does not check for duplicate copies of     
messages across multiple mailboxes since it is often useful to   
cross-file messages in multiple mailboxes.                       
                                                                 
Usage:  delIMAPdups -S host/user/password                         

Optional Arguments:

-i <list of users and passwords>  (format: user password)
-A <admin_user:admin_password>
-m <mailbox list>                       
-p delete the duplicates
-M <mailbox>   Move duplicate msgs to this mailbox instead of deleting them.
-u include the date in determining if a message is unique, not just the message-id
-L <logfile>                
-d debug
-H Use an MD5-digest hash of the message body instead of the Message-Id
-F <header field> Instead of the Message-Id use a different header field to 
determine uniqueness, eg Subject or From.

migrateIMAP is a utility for mass migration of messages for a 
set of users from one IMAP server to another.
                                                                     
Usage: migrateIMAP -S host1 -D host2 -i <users file>
                                                                     
Optional arguments:                                               

-n maxChildren
-d debug                                                      
-I show IMAP protocol exchanges
-a <DD-MMM-YYYY> Migrate only those messages after the specifed date.
-b <DD-MMM-YYYY> Migrate only those messages before the specifed date.
-x <delimiter [prefix]> Specify the src mbx delimiter and prefix (if server does not support NAMESPACE command)
-y <delimiter [prefix]> Specify the dst mbx delimiter and prefix (if server does not support NAMESPACE command)
-M <file of mailbox name mappings>.  See description of imapcopy.pl for details.
-L logfile                                                    
-U (update mode)
-u Copy only Unseen (unread) messages
-o Copy only Seen (read) messages
-X (in update mode remove messages from the dest which are not on the source)
-e  sourceAdminName:sourceAdminPassword
-f  destAdminName:destAdminPassword
-E <mailbox list> (exclude the listed mailboxes, eg "Trash,Wastebasket,etc")
-R <mailbox list> (exlucde the listed mailboxes using regular expressions)
-w (destination is an Exchange server, which limits mailbox creations to 9 per IMAP session).
-G (source passwords are XOAUTH2 tokens used with AUTHENTICATE XOAUTH2)
-J (destination passwords are XOAUTH2 tokens used with AUTHENTICATE XOAUTH2)

The user list file (-i <file>) should contain entries like this:              
    sourceUser1:password:destinationUser1:password               
    sourceUser2:password:destinationUser2:password               
    etc                                                           

The maxChildren argument specifies how many child processes will be executed
in parallel (the default is 2).  The optimum number of children depends on
the system's resources but usually 4 or 5 maximizes the performance.  Beyond
those numbers there is too much contention for resources to obtain additional
improvement.

Note:  On Windows the number of processes is limited to 1 since Windows does not
support the fork() system call.

migrateIMAP supports AUTHENTICATION=PLAIN which permits you to supply an administrator
name and password instead of having to provide each user's password.  This is very
convenient when doing mass migrations if your IMAP server supports it.  Please see
Admin mode for details on how to configure it.

imapCapability queries an IMAP server and reports which IMAP services
it supports.
                                                                     
Usage: imapCapability.pl -h <host> -u <username> -p <password>
                                                                     
Optional arguments:                                               

-d debug                                                      
-m list the user's folders
-A <admin_user:admin_password>

# ./imapCapability.pl -h localhost:1430 -u rfs9999 -p mysecret

The server supports the following IMAP capabilities:

IMAP4 IMAP4REV1 ACL NAMESPACE UIDPLUS IDLE LITERAL+ QUOTA 
ID MULTIAPPEND LISTEXT CHILDREN BINARY LOGIN-REFERRALS 
UNSELECT STARTTLS AUTH=LOGIN AUTH=PLAIN AUTH=CRAM-MD5 
AUTH=DIGEST-MD5 AUTH=GSSAPI AUTH=MSN AUTH=NTLM

Please refer to the IMAP RFCs for an explanation of these capabilities.

list_imap_folders.pl will display a list of the user's folders.

Usage: list_imap_folders.pl -S host/user/mypassword [-O output file]
       [-A <admin_user:admin_password>]
       [-l ]
       [-s]
       [-U <size in bytes>]

AAA
BOGUS
Big.Box
Drafts
INBOX
INBOX/MOVED
INBOX/MOVED/Where
International
MOVED
etc

If -s is used then the list will include the size of the folder as well.  

LDAP   (5 msgs, 0.06 MB)
MOVED  (2 msgs, 0.19 MB)
Martin (12 msgs, 0.39 MB)
Medical (5 msgs, 0.01 MB)

If -U <size in bytes> is included then a file named large_msg_report.txt
will be written containing messages exceeding the size threshold (along with
the subject of the message.) For example:

INBOX   (1.2 MB) Easy Tailgating Recipes
International  (9.8 MB) Project, 2010 

You can supply passwords in the users list instead of using admin_mode:

john:password
joan:secret
tom:xxxxxx

imap_audit can be used to compare the contents of a user's account on  
one IMAP server with an account on another IMAP server.  It is often    
useful after migrating a user to another server to check that all 
messages were successfully copied. 

imap_audit.pl -S sourceHost/sourceUser/sourcePassword
                 -D destHost/destUser/destPassword
                 -d debug
                 -I show IMAP commands/responses
                 -L logfile
                 -u  format srcuser:srcpwd:dstuser:dstpwd
                 [-E source_admin_user:source_admin_password]
                 [-F destination_admin_user:destionation_admin_password]
                 [-d debug]
                 [-I show IMAP commands/responses]
                 [-m  comma-separated list of mbxs to check]
                 [-n display count of msgs in folders]

list_account_sizes.pl can be used as a pre-migration planning tool to determine
the size of each account to be migrated as well as the total number of MBs which
will be copied.  It produces a report that looks like this:

        SIZE (MB)       USER                                                    
       ==================================================                       
       1,583.27        jessi                                                    
       1,429.61        tom                                                      
       1,260.20        john                                                     
         691.07        jane                                                     
          45.18        bob                                                      
                                                                                
       Totals                                                                   
       =================                                                        
       Users    5                                                               
       Bytes    5,009.33 MB                                                     

The command to execute list_account_sizes.pl is:
 
      ./list_account_sizes.pl -S <host> -u <list of users> [-A admin:password]  
                                                                                
If you supply the name and password for an administrator who can log into a  
user's account then the user list is just account names; otherwise you must  
supply the users's passwords in the list:                                    

       john:mypass                                                              
       mary:herpassword                                                         
       etc

imap_search.pl is used to search a user's mailbox for
messages matching a set of search criteria. By default all 
folders are searched but you can limit the search to a single
folder if desired.

For example, let's say you want to find all messages sent by john.lombard:

./imap_search.pl host/user/password from=john.lombard@aol.com

Searching for from "john.lombard@aol.com" in all folders

Folder               Date                          Subject              
=====================================================================
Gmail/Important  18 Aug 2012 09:31:09         property 13251984
INBOX            03 Dec 2013 11:10:01         subscribe test_list
INBOX            07 Sep 2012 01:11:05         property 33951800
INBOX            07 Sep 2012 01:12:25         RE: meeting tomorrow
TRASH            03 Dec 2013 18:10:01         hello

You can combine filter expressions as well:

OR from=tom from=charles
AND subject=test from=marie
"subject=sales meeting" NOT from=linda
from=Mary subject=notification
subject=password NOT subject=new
sentsince=10-Nov-2013
sentbefore=1-Jan-2001
on=5-Dec-2013
"body=agenda for today"

Note that the SEARCH command is not a very sophisticated command as specified
by the IMAP RFCs so you will want to keep your searches fairly simple.
If your search expression is not acceptable to IMAP you'll get a syntax error.
After some testing you will find what works on your IMAP server (some fields
aren't searchable on some servers while they work on others.  It seems
to be implementation-specific).

In some cases you have to insert 'header' to tell the IMAP server to search
the ENVELOPE rather than the content header: header Received=xxxxx.

Administrator mode
It is a pain having to supply a user's password with each search so imap_search
supports admin mode where you can give the administrator's username and pwd
instead.  For example:  host/user:admin_user/admin_password

Configuration file
Another way to simplify searching is by setting up an imap_search configuration file
with the following lines:

server:     imap.myserver.com
admin_user: administrator
admin_pwd:  secret

You can put the config file in your local directory, /etc, /usr/bin, or /var/tmp and imap_search
will find it.  Then you just have to supply the username instead of host/user/password:

./imap_search.pl user from=somebody

Much easier, isn't it?

Single folder search
By default imap_search searches all folders but you may want to narrow the search
to save time, for example by searching just the inbox.  To limit the search
place the name of the folder at the end of the access string like this:

host/user/password:Inbox
user:Drafts

Notes:

o  Searches are case-insensitive
o  Mailbox names are case-sensitive
o  Regular expressions are not permitted
o  Wildcards are implied, eg subject=test matches every subject which has
the string "test" in it
o  Search values containing spaces must be quoted:  suubject="this is the day"
o  "Body" searches take longer since the body of each message has to be searched
o  Dates must be in DD-MM-YYYY format without the timestamp or timezone 
o  See the IMAP RFC for a listing of all IMAP SEARCH keywords or visit:
 http://www.afterlogic.com/mailbee-net/docs/MailBee.ImapMail.Imap.Search_overload_1.html