File	Date	Author	Commit
README	2016-04-19	Michael	[fde700] added license text
imaputils.pl	2024-06-28	Michael Baer	[b21033] adding verbose ability for usage output, e.g. d...

Read Me

1 Index
2 Intro
3 Install Requirements
4 Configuration file
5 Usage
6 Examples
6 Actual Examples


2 Intro:

'imaputils' is a tool written in Perl for managing/searching mail on
an IMAP servers from the command line.  Since it uses the native
IMAP server to do the requests, it depends on what options those
servers support.  Imaputils has been used with dovecot and Google's
IMAP servers with success, but your mileage may vary depending on
the IMAP server you are using.  Also the SSL and local socket
connection options have been used quite a bit, but the plain-text
connection has not (so it is not well tested).

* CLI tool written in Perl
* Search using the native IMAP server's capabilities: date, mail
  header, etc. (See 'Constraints' in usage for what you can search
  on)
* Move, copy, delete, etc. (See 'Actions' in usage for what you can
  do)


3 Installation Requirements

  Place the script wherever you want to call it from (/usr/bin,
  $HOME/bin, etc.).  It requires the following modules to work.  And
  thanks to all of the people who worked on them, particular
  Mail::IMAPClient, as that is the main module this tools relies on.

    Perl
	Perl modules:
        Mail::IMAPClient;
        IO::Socket::SSL;
        DateTime::Format::Mail;
        Getopt::Long;

    socat
        Needed for local socket connections, otherwise not needed.


4 Configuration file

$HOME/.imaputilsrc is the default configuration file.  If it exists
it will be read.  The options in the configuration file are
identical to the command line options without '--'.  Anything after
a '#' character in the config file is ignored.

e.g.:
# my config file
ssl
pass mypassword
host imap.example.com
user someuser

The command line has precedence.  Any option given at the command
line will override the options found in the configuration file.  You
can also pass a location of the config file to imaputils using the
'--config' command line option.

The configuration file options are identical to the command line
options below.  You can just place those options you use most often
into the config file to save typing at the command line.  The
connection options are the best example of this: host, user,
password, imapexec, ssl, etc..  

For a more complex example, Dovecot does not seem to run well in my
default shell and I need to set some environmental variables before
running dovecot (non-standard setup).  Because of this I set the
imapexec option in .imaptutilsrc to point to a bash-shell script
that sets the environment and calls the dovecot executable.  The
'imapexec' option is only used for local socket connections and
doesn't affect imaputils network connection.

Also, for fun you could just set up whatever commands you want to
run in a file and pass that file to imaputils with '--config'. 
Let's say you you just want to check your mail,

$ cat checkmailrc
# check mail config file
ssl
host imap.example.com
pass mypassword
user someuser
box  INBOX,favlist,friendbox
newmail

$ imaputils.pl --config checkmailrc
INBOX 2
favlist 0
friendbox 0


5 Usage

Here's the usage.  This is where most of the explanation exists
because, well, I'm lazy and want to keep the documentation in as
few of places as possible.

Usage:
  ./imaputils.pl connection-opts [mailbox(es)] action [contraint(s)]

Connection Options:
	--host     string : host
	--user     string : user
	--password string : password
	--ssl             : use a SSL socket to connect
	--sslport  number : use as the SSL port (default: 993)
	--socket          : connect using a LOCAL socket (default)
	--imapexec string : IMAP executable to use if connecting using
	                    a LOCAL socket (default: /usr/libexec/dovecot/imap)
	--socatexec string: socat executable to use if connecting using
	                    a LOCAL socket (default: socat)

to server: only useful for --copy or --move
	--tohost      string : host
	--touser      string : user
	--topassword  string : password
	--tossl              : use a SSL socket to connect
	--tosslport   number : use as the SSL port (default: 993)
	--tosocket           : connect using a LOCAL socket (default)
	--toimapexec  string : IMAP executable to use if connecting using
	                       a LOCAL socket (default: /usr/libexec/dovecot/imap)
	--tosocatexec string : socat executable to use if connecting using
	                       a LOCAL socket (default: socat)

Mailboxes:
	--box   string : comma delimited list of mail box names
	                 (required for most commands),
	--tobox string : single box name

Actions (with no contraints):
	--mailboxes : list imap mailboxes on the server
	--create    : creates a new mailbox named using '--box'
	--info      : lists info about the mailbox named using '--box'
	--newmail   : counts new mail in '--box'

Actions (requiring 1+ constraints)
	--copy       : copy mail found in '--box' to '--tobox'
	               (fails if --tobox doesn't exist (dovecot))
	--move       : move mail found in '--box' to '--tobox'
	               (creates --tobox if it doesn't exist (dovecot))
	--list       : list UIDs of mail found in '--box'
	--listheader : list mail headers of mail found in '--box'
	--listfullheader : list all mail headers of mail found in '--box'
	--showrecieved : Show received heaer when listing headers
	--count      : count mail found in '--box'
	--delete     : delete mail found in '--box'
	--display    : displays the mail found, max 10

Constraints: messages searched based on the Intersection (AND)
             of up to one each of the following constraints.
	--or         Union (OR) of constraints instead
	--sentsince  date   : since header Date: (dd-Mon-YYYY or unixtime)
	--sentbefore date   : before header Date: (dd-Mon-YYYY or unixtime)
	--senton     date   : on header Date: (dd-Mon-YYYY or unixtime)
	--since      date   : since received date (dd-Mon-YYYY or in unixtime)
	--before     date   : before received date (dd-Mon-YYYY or unixtime)
	--on         date   : on received date (dd-Mon-YYYY or unixtime)
	--subject       string : caseless string in Subject: header
	--from          string : caseless string in From: header
	--to            string : caseless string in To: header
	--cc            string : caseless string in Cc: header
	--tocc          string : caseless string in Cc: or To: header
	--body          string : caseless string in body of message
	--headercontent string : caseless string in header of message
	--uids          string : comma delimited string of uids
	--seen       messages that have been seen
	--unseen     messages that have not been seen
	  spamassassin headers are defined in @spam_score_headers
	               (default: X-Spam-Status)
	--spamg      score : messages with spam header score > 'score'
	--spaml      score : messages with spam header score < 'score'
	--spame      score : messages with spam header score = 'score'
	--baddate    character : a = all
	                         b = rec. date != Date: ± 30 days
	                         n = no Date:
	                         p = unparsable Date:
	--strictdate When parsing date for baddate, use strict checker

Misc:
	--regexp     use regular expresions on header searches (slower):
	                 e.g. subject, from, to, cc, tocc
	--config     string : configuration file to use
	                     (def: $HOME/.imaputilsrc)
	--nopeek     Normally imaputils.pl tries to not mark email as
	                 'seen'. This option turns that off.
	--verbose or -v      mostly this shows all the uids
	--usage   or -h      this message


6 Examples

I need examples to figure out how to use something, so I'm going try
to give some here.  

For the examples, the connection info is assumed to be in
.imaputilsrc.  

That is, for network connections you need some combo of options:

ssl,host,user,pass 

(or possibly just 'host,user,pass' if you don't use ssl, but why the
heck not?!, or maybe you are paranoid and just have 'ssl,host,user'
in .imaputilsrc and always put 'pass' on the command line or... you
get the idea)

For a local socket connection (the IMAP server is on the local
machine and you have socat installed) you may need no connection
options.  Or you may have to set 'imapexec' because you're not using
dovecot (the default) or the dovecot IMAP executable is in a
different place on your box or you have to adjust the environment
 to run it, or... you just need to customize it in some way.


7 Actual Examples

Archive last years mail (assuming connection info 'host, user, ssl,
pass' is in .imaputilsrc):

imaputils.pl --sentbefore 01-jan-2010 --sentsince 01-jan-2009 --move --box INBOX --tobox archive-2009


Did fred send me something in the last week?

$ imaputils.pl --from fred  --sentsince 03-Sep-2010 --box INBOX,friendbox,spam --count


Did fred send me something in 2009?

$ imaputils.pl --from fred  --sentsince 01-Jan-2009 --sentbefore 01-Jan-2010 --box INBOX,friendbox,archive-2009 --count


Did I get something with the subject 'important spam' last week

$ imaputils.pl --subject 'important spam'  --sentsince 03-Sep-2010 --box INBOX,spam --count


Hmm, what do those headers (simple) look like?

$ imaputils.pl --subject 'important spam'  --sentsince 03-Sep-2010 --box INBOX,spam --listheaders


For some crazy reason I'm going to treat this like a mail reader and look at what is in all those emails (maybe I just like spam?)

$ imaputils.pl --subject 'important spam'  --sentsince 03-Sep-2010 --box INBOX,spam --display


Do I have any newmail?

$ imaputils.pl --newmail --box INBOX,spam,yolist


What is the list of all my mailboxes?

$ imaputils.pl --mailboxes


Do I want more info than I really want about a mailbox?

$ imaputils.pl --info --box INBOX


What is the count all mail in a mailbox?

$ imaputils.pl --box INBOX --count --sentsince 0

(a single number passed to --sentsince, '0' in this case, is
interpreted as the unix time, so this should select everything in
the mailbox)