imaputils git
Status: Beta
Brought to you by:
baerm
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... |
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)