popfind: CMD Line POP Mailbox Search, View, and Delete

In the very early days of email, I stumbled across a POP mailbox utility that would simply scan the POP server, and then either forward or delete messages based on a few simple critera. At the time, this was a great utility – I wanted to forward personal email to my work email during the day and this was one of the things it could do.

Eventually I no longer needed the utility, uninstalled it, and somehow lost the install file. Over the years I have often found I could have used it again for some project. I’ve searched for something like it repeatedly and never found anything even close.

Even if I did still have it, I know it wouldn’t work. The days of unencrypted email access are over. Gmail and Yahoo’s POP access requires SSL encryption – and these days I wouldn’t go without it myself.

To make matters worse, email messages are now full of HTML and Mime objects that would easily make that old POP utility worthless.

Again, I find myself really needing the ability to manipulate a POP server from the command line. I need to be able to determine if a message is on the server, extract it to a flat file for further processing, and finally delete it from the server.

I wrote popfind to perform these functions. It will locate a message based on various criteria (from, to, subject, text in the body). It can then view or delete that message.

popfind was meant to be used inside of a script. You will need to be comfortable scripting in dos or linux to truly make use of this utility. I include examples of using the utility, but explaining how to use it in a script is beyond the scope of this document.


popfind {<searchstr>|<uid>}
    -a | --action  {find | view | delete}
    -c | --config  <fname>
    -d             Same as --action delete
    -f | --from    <str>
    -h | --help
    -l | --login   <host>,<user>,<pass>[,<port>]
    -m | --maxsize <kb>
    -r | --range   {first | all}
    -s | --subject <str>
    -t | --to      <str>
    -v             Same as --action view
         --verbose Display debugging
    -w | --write   <fname>

–action: indicates if you want to find a matching message (or messages), view a message, or delete a message. The default action is find.

–config: loads a configuration file so –login may be omitted.

-d: Same as –action delete.

–from: search from address for string.

–help: Explanation of the program.

–login: Specify the host, user name, password, and port to use to access the POP server. Only the port can be omitted, in which case the default is 110. If the port is 110, non-SSL access will be used. If the port is any other value, SSL access is used.

Warning: If your password contains a comma (,), you must delimit your password with single quotes such as ‘pass,word’. Double quotes will NOT work.

–maxsize: The maximum number of kilobytes to download. The default is 10KB. This program will scan the entire POP server mailbox each time it is run until a match is found. Limiting the amount of data downloaded for each message will allow it to run faster.

The email may have a lot of invisible overhead you can’t see in an email client (HTML, jpg files, etc.), so the maxsize may need to be larger than you might expect.

–range: By default, the program will exit after finding the first matching message. If you want to find all matching messages, then use –range all.

–subject: search subject for string.

–to: search list of to addresses (there may be more than one) for string.

-v: same as –action view.

–verbose: Enables debugging information.

–version: Displays the version of the program and the date compiled.

–write: Creates a configuration file using the specified –login command. The contents of the configuration file are scrambled up but they are NOT encrypted. This only prevents someone from easily looking over your shoulder and seeing your email password. You should secure the configuration file so other may not see it.

Warning: There is a bug in the command line parser library I’m using and –write fails to work properly, but -w works just fine. It’s on my todolist to fix this, but I imagine it will be a long time before I get to it.


By default, popfind searches messages in a POP mailbox looking for messages that contain <searchStr> in either the subject OR the body of the messsage.

If a matching message is found, then the unique ID (UID) of the message is printed and the exitcode is set to 0.

If no message is found, an error is printed (to stderr) and exitcode is set to 1.

If any other error occurs, the program aborts and exitcode is set to the corresponding error (> 1).

Additional criteria may be specified with –from, –to, and –subject.

The default action is for popfind to search for <searchStr>. If you specify an action of view or delete, then <searchStr> is the UID of the message to view or delete.

Normally, popfind will stop searching after the first message is found. If you want it to find all messsages that match the criteria, specify –range all.

If you don’t specify any criteria, then all messsages will match.


The primary function of popfind is to locate an email on the POP server.

popfind --login pop.gmail.com,user@gmail.com,password,995 "test"

To make it a bit easier to type the command, the –login information can be saved to a configuration file:

popfind --login pop.gmail.com,user@gmail.com,password,995 --write gmail.cfg

Remember, this file is NOT encrypted. If you use it, you should make sure it is secured from others.

Once a messsage is found, you can view it (or save a copy to disk for further processing). Just use the message UID returned during the find action:

popfind -c gmail.cfg -v GmailId14be795cf61179d6
From: fred gwyne <x@gmail.com>
To: x@gmail.com
Subject: test subject
Date: 3/4/2015 17:38:49
MessageID: CAM-h2d-a_TRm-7H85eTamFRS-jadJhFPuxxzi3zmNiUm==BMgw@mail.gmail.com

test body

To output the message to a text file, just redirect it:

popfind -c gmail.cfg -v GmailId14be795cf61179d6 >msg.txt

Once you are done with the message, you probably want to delete it from the POP server so it won’t be matched again. This is done with the delete action:

popfind -c gmail.cfg -d GmailId14be795cf61179d6

If you want to find all messages on the server, use the –range all option and don’t specify any criteria:

popfind>popfind -c gmail.cfg -r all

To find all messages from a particular address, use –from:

popfind -c gmail.cfg -f fred -r all

Each of the criteria, –from, –to, –subject, and <searchStr> are ANDed to select the message. So to find a message from fred AND to pop AND with subject abc AND with body containing def  do the following:

popfind -c gmail.cfg -f fred -t pop -s abc def

The options –to, –from, and –subject can be given strings with spaces by enclosing them in double quotes such as

C:\Users\danh\Desktop\popfind>popfind -c gmail.cfg -s "test 1"

This is not required for <searchStr>, though you can use them:

C:\Users\danh\Desktop\popfind>popfind -c gmail.cfg "test 1"

If your criteria isn’t working the way you would expect, use –verbose to see how the command line has been parsed. That may help you determine why a match is not occurring:



I wrote popfind in free pascal which means the exact same source can be used for Windows, x86 Linux, Raspberry Pi Linux, and Mac.

I have compiled and tested the program under  Windows, x86 Linux, and Raspberry Pi. Follow the appropriate Download/Install for the platform you are using.


Download the version appropriate for your computer:

Install Windows Version

Create a directory and unzip the files into that directory. You may wish to set your PATH to this new directory.

popfind requires 3 DLLs. Those DLLs are in the zip file. They should typically remain in the same directory as the popfind program.

If the DLLs aren’t properly loaded, you may receive an error indicating the missing DLL, but you may just receive an error indicating the mailbox cannot be opened.

Install Linux Version

Extract the popfind program from the compressed archive file. Place the file in an appropriate directory. Make sure it has eXecute access. You probably want to change the file’s user and group as well.

popfind requires the libraries libssl.so and libcrypto.so. You can do the following to verify if the files are already installed:

sudo find / -name libssl.so
sudo find / -name libcrypto.so

If the files are missing, the only error you will get is that the mailbox cannot be opened. There is no indication the library files are missing.

Use the following to install the library files (this has worked properly for me on Linux Mint and Raspian):

sudo apt-get update
sudo apt-get install libssl-dev


I start testing by just using the –login parameter:

popfind --login host,user,pass,995

This will simply return the first UID found. Once you know you can access the mailbox, then you can start using other options.

If login fails, use –verbose to verify that the login parameter has been parsed as you expect.

You can also use wireshark to examine the network session between yourself and your POP server.

If your POP server supports unencrypted connections, see if you can get that to work.


This entry was posted in c-pcos and tagged . Bookmark the permalink.

11 Responses to popfind: CMD Line POP Mailbox Search, View, and Delete

  1. Pingback: Make a Raspberry Pi Act on an Email Message | Big Dan the Blogging Man

  2. alex says:

    HI, I am using it on my raspberry pi. Unfortunately, the cfg file is not written (everything else looks fine). Any idea?

    • Dan TheMan says:

      Not quite sure what you mean by “not written”. You create the cfg yourself to use as input to popfind so you don’t have to include the –login each time.

      • Dan TheMan says:

        Ah, I had forgotten about -w to create the config command.
        I retested this on my RPI using my normal user (e.g. I didn’t use sudo). It created the cfg fine for me.

        I checked the code and I simply call the TString object’s SaveToFile method. So that method is dying for some unexpected reason. Are you sure you have write access to the directory and the filename doesn’t have invalid characters?

        For my test, I simply entered:

        popfind -l pop.gmail.com,myuser@gmail.com,mypass,995 -w test.cfg

        and that properly created test.cfg.

  3. Alex says:

    Hi, I found the issue: I was using –write. With -w it is working fine (cfg file gets created)

    • Dan TheMan says:

      I’ve duplicated the problem. Using -w works and –write fails. Looking at the code, it appears to be an issue of some sort in the library I use to parse command line options.

      Temporary Fix: use -w not –write.

  4. Logan says:

    Hey Dan, first this is an awesome idea, and exactly the kind of thing I was looking for. I have a similar project in mind to your garage door opener and I was hoping to leverage your popfind utility to make it happen. I know this thread is a couple years old now, but I was hoping you could tell me why I am getting this error?

    An unhandled exception occurred at $00046D40 :
    ERangeError : Range check error

    I am trying to run popfind on a raspberry pi 3 with raspian 8 and this error occurs whenever I try to run the login command.I am trying to connect to a gmail account with pop enabled using the following line: ./popfind –login pop.gmail.com, email@gmail.com, password, 995 but I only get the above error. Thanks again for creating such a neat tool!

    • Dan TheMan says:

      Along with the other options you use, please include -v option and let me know what it displays, mangling any email addresses you don’t want to make public. That should at least get me to close to the right section of code with the issue.

    • Dan TheMan says:

      BTW, you DID see that using -w will fail and –write works OK. It has been so long, I don’t recall what the error is if you use -w. Might be the range error, might now.

      • Logan says:

        Yeah, I did see that, but I get the error even when I am not using -w/write. I actually can’t get it to work at all.

      • Logan says:

        Okay I figured out what I was doing wrong, and I feel very silly… the arguments to popfind must not have spaces between them they are only delimited by the commas, if you add a space as well you get that error. In other words Do: popfind -l pop.gmail.com,user@gmail.com,pwd,995 Don’t do: popfind -l pop.gmail.com, user@gmail.com, pwd, 995 I guess this should have been obvious from how you typed it in the tutorial, my bad.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.