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:
/usr/bin/imaputils.pl connection-opts [mailbox(es)] action [contraint(s)]
Connection Options:
--host string : host
--user string : user
--password string : password
--socket : connect using a LOCAL socket (default)
--imapexec string : IMAP executable to use if connecting using
a LOCAL socket (default: /usr/libexec/dovecot/imap)
SSL:
--ssl : use a SSL socket to connect
--sslport number : use as the SSL port (default: 993)
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'
--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.
--sentsince date : dd-Mon-YYYY, RFC 2060 format (or in unixtime)
--sentbefore date : dd-Mon-YYYY, RFC 2060 format (or in unixtime)
--senton date : dd-Mon-YYYY, RFC 2060 format (or in unixtime)
--subject string : caseless match
--from string : caseless match
--to string : caseless match
--cc string : caseless match
--tocc string : caseless match, string in Cc: or To: header
--body string : caseless match, in body of message
--uids string : comma delimited string of uids
--seen messages that have been seen
--unseen messages that have not been seen
--baddate character : a = all,
b = internaldate != Date: +/- 30 days
n = no/bad Date: field
Misc:
--regexp do regexp on header searches (experimental,slower)
--config string : configuration file to use
(def: $HOME/.imaputilsrc)
--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)
