IMAPTool.Exe  program documentation

This Windows® program provides access to IMAP (Internet Message Access Protocol) using a command line interface.  IMAP4 is the primary protocol used to access received email.  The older, and now less frequently used, email retrieval protocol is POP3 (Post Office Protocol.)  An identifying aspect of POP3 is that email is read from the remote email server, copied to the client device (i.e., your computer), then deleted from the email server.  Identifying aspects of IMAP are that multiple devices (e.g., a computer and a cell phone or tablet) can access the same email account, and that emails can be moved between individual folders.

Purpose

This program was created in order to learn how to use IMAP and perform some specific, simple, tasks: examining email, taking some automatic action, then possibly moving each one to another folder, deleting it, or creating a license file, for example.  It soon became obvious that IMAP has some very useful features which email clients frequently do not make available to users in email client software, as well as some additional features that would be nice to have, but that it doesn't have.  This program is therefore provided as both a learning tool and an access tool to all of the feaures of the IMAP protocol as well as some added features.  Two of those added features are automated email handling and filtering based on the subject or sender and counting emails, based on the sender.


Configuration options

Although IMAPTool has numerous configuration options, but it can be started with this very simple command: IMAPTool.  It will ask for the parameters as it needs them; they are: the name of the email server, the port to use to connect to it, the email account name, and the email account password.  To simplify a logon, any or all four (4) of these parameters, as well as all other options, may be stored in a text-based configuration file or placed in an environment variable.  The environment variable that the program checks has the program's base name, and may contain multiple configuration parameters, initialized using  Set IMAPTool=/Simap.mail.com/Uusername/P993 , for example.  Here are a couple suggestions:
  1. ) Use the  /NoPrompt  option to prevent the program from asking to verify that each of the four (4) required parameters is correct.
  2. ) Keep all parameters except the email account password in a configuration file and type only the password in at run time.
By default, the program will display dots instead of the actual account password when prompting.  The email password can also be placed in the configuration file or an environment variable, of course, based on your individual security requirements.


Commands

The program has both command line help and extensive help available after connecting to the email server; more on that in the next section.  The command to remember is how to generate that help output:
  IMAPTool ?
  IMAPTool /?
Either of these print the help sequence, the configurable parameter list, to the console.  Most of the default parameters should work well for most situations and won't need to be changed, but some are of particular interest.

  IMAPTool /Simap.emailserver.com
  IMAPTool /Simap.emailserver.com:993
  IMAPTool /Host=imap.emailserver.com:993
This is how the email server name can be specified on a command line, with the option to add the port on which it is listening for a connection.  The '=' is optional.  The syntax for configuration file commands is almost the same — just omit the program name.  The leading slash can also be omitted.  For example, the middle command above would simply change to:
  Simap.emailserver.com:993

The syntax for the other three (3) required parameters, with the program name omitted:
  /P993
  /UAccountUserName
  /PAccountPassword
The "/P" could certainly be confused, since it is used to set either port or password.  If the first character after the 'P' is '0' through '9', it's treated as the port, otherwise, it's treated as a password.  There are actually two other uses for "/P". 
  /P?
As you likely have already guessed, the "?" is a information request.  It displays both the port number and the "Purge Message" state.
  /P+     /P-     /P^
The "/P+" enables the "Purge Message" mode, "/P-" disables it, and "/P^" toggles it.  This is only used if wanting to purge messages from the temporary HEAP-based buffers; it is disabled by default.  In addition to the Port parameter, these are the other numeric options and what each option affects:

  /Anumber
This is the receive buffer HEAP allocation, for which the default is 16,384 BYTEs.  If a reply exceeds this BYTE count, it is placed in another, larger, dynamically allocated buffer.  The body of an email can be quite large, especially if there are attachments.  Although this program doesn't routinely examine the email body, it can be requested on command.  If it is too large, the program will prompt to discard the reply, or save it to disk.

  /D[number]
These are debug values, covered in the Debug section, below.

  /Hnumber
This is the socket receive buffer size.  Since only email headers are routinely requested, its default of 4,096 BYTEs should be adequate for most uses.

  /Inumber
While obtaining the number of times an email has been received from each sender eddress, the program requests only the From: field for a block with a range of email tags.  This value is how many it requests per block, and its default is ten (10) eddresses.

  /K[number]
Most email hosts will close the connection if there is no input for some time;  This is typically about ten (10) to twelve (12) minutes.  Setting this value causes a periodic "keep-alive" or "no op" message, NOOP, to be sent to prevent logout.  If its value is zero, the default, it is off.  If /K alone is given, it is set to 600 seconds, or ten (10) minutes.

  /L[number]
This value sets the login step on which to end, and is seven (7), by default.  To examine, or debug, the login process, it can be set to a lower value, but usually should be left at its default.

  /D[number]
These are OpenSSL debug values, covered in the Debug section.

  /Znumber
This sets the reply time limit for each email query sent.  Its default is 330 milliseconds.

  /ZZnumber
While no command is being processed, the program "goes to sleep" briefly, so as not to take all CPU time.  This is the number of milliseconds the operating system is told to allow it to sleep; the default is 25.

  /Ffilename.cfg
The command above is used to specify the name of a configuration file to be loaded if it is not IMAPTool.Cfg, the default.  This to be able to access different email accounts or to simply use a different parameter set.  One could have just a move list and another a purge list, for example.  The desired configuration file name can be placed either on the command line or in an environment variable, for example:
  Set IMAPTool=/FAltName.Cfg
As can be deduced, the environment variable is checked and, if present, read before attempting to read a configuration file.  The command line is read twice, both first and last.  Because of this, any parameters specified on the command line will have the highest priority and will override the same parameter in the environment or in a configuration file.

Finally, any request (or "query" or "command") string can be sent to the IMAP server; details are in the next section.


Online help

Help is available after the program has started.  Type ? to display the main help output.  Some commands can be abbreviated — for example, CR for Create, and F for Fetch.  This is as good a place as any to suggest that the IMAPTool console window size be set to 50-line mode, with an optional larger screen buffer line value (suggest 1,000 or more.)  To set the console display to just 80 columns by 50 rows, the system command  Mode Con Cols=80 Lines=50  could be used.

All of the IMAP commands which IMAPTool directly supports are listed on that help page.  Each one has further context sensitive help, invoked by typing the command or its acceptable abbreviation, and a ? somewhere on the line before pressing Enter.  Since most IMAP servers are somewhat picky about the command syntax (e.g., the return an error if two spaces are entered when it is expecting only one), the supported shortcut command which you enter is formatted and transmitted to the IMAP server using the expected syntax.  Also, if a supported command accepts or requires multiple parameters, they can be entered in any unambiguous order, for example:
  Store + Deleted 100:104
would transmit the command to the IMAP server in its expected format:
  5604 Store 100:104 +Flags \Deleted
and
  sto delt - 100-104
sends this string to the IMAP server:
  5605 Store 100:104 -Flags \Deleted

Notice that IMAPTool prepends the required 4-digit hexadecimal IMAP message sequence number (5604 and 5605 in the examples above, called a 'tag') that identifies which reply belongs to which query.  It also supports transmitting any string to the IMAP server, more than those directly supported.  To do this, simply type a single space before the string to send.  The next sequential IMAP tag will be prepended and the string sent with the only other editing being the appended Carriage Return and Line Feed.  Any reply from the IMAP server is output (unless output is disabled.)  Also, the acceptable abbreviation for "Deleted" is "de" (case is not important), but that the "delt" shown is a misspelling of "Deleted".  Superfluous characters after a keyword are usually benign and ignored.

The take-away here is that IMAPTool is designed to enable experimentation with the syntax of the IMAP protocol.  It could be just for curiosity, or maybe to learn about the protocol and how to interact with an IMAP server.

Since there is so much online help, it would unnecessarily lengthen this section to describe the help for each of the IMAP protocol's commands any further.  One other note: the  /P?  described above does not invoke help, but displays the port number.  This is because any command beginning with a slash is passed to the command line processor.  This means that many of the values set on startup, or even the default values, can be changed while already online.  For example, the command  /K=480  could be used to change the "Keep-Alive" time to 8 Minutes, even if none was specified before starting IMAPTool.


Capture to a file

In order to be able save a portion (or all) of the output generated to the console screen to review, IMAPTool has a capture feature.  In order to use it, the first configuration command must be one to define a Function Key which toggles capture to disk.
  Capture=FunctionKeypress

The FunctionKeypress parameter is defined as F1 through F12, with modifiers in the first character after the '=' and before the 'F' being 'A', 'C', or 'S', for "Alt", "Control" or "Shift".  These all select the same function keypress: CF12, C-F12, CtrlF12, Ctrl-F12, Control-F12, or even ckey-f12.  None of 'A', 'C', 'F', and 'S' are case sensitive when specifying a capture function key.

Only after a capture function key is defined is the following accepted:
  Capture=True   opens the capture file before the first text is output.
These two commands are best placed together in a configuration file or in an environment variable. 

A unique capture file name is created, which contains the date and time the file was opened.  Each has the extension .Cap.  If capture is toggled on, then toggled off, then on again, two different files are created.  Example: 20220930_130405.Cap would have been created just after lunchtime (1:04:05 PM) on Friday, September 30, 2022.  The cursor is modified (into a large block) while capture to disk is active.  The capture file is automatically closed when the program ends if not closed beforehand; the cursor is restored on normal program exit.

There are two additional capture-related options, the results of which only appear in the capture file:
 CaptureColor notes each text color change, and
 CaptureTime places time notes in the capture file.
In actual use, those two rather overwhelm and clutter the capture file (as in "TMI".)


Counting email senders

This and all remaining commands are not part of the IMAP protocol.  The purpose of this command is to provide a list of sender eddresses to edit in order to create items for the WhiteList, BlackList, and/or MoveList commands.  It provides the ability to scan through a range of emails and record how many times each unique eddress is encountered.  Its syntax is:
  Cou[nt] [StartTag][:EndTag|-EndTag] [options]

If only  Count  with options following (or no options at all), the StartTag is assumed to be 1 and the EndTag is the last email in the default folder or mailbox, which is INBOX unless changed using the  /Nfolder  startup command.  This first option permits a folder other than the default to be changed for the duration of processing the command, without changing the default folder, for example:
  Count 11:99 Folder:DRAFTS

A block of options enable sorting after the counting logic has completed.  In order to not list them twice, all of the post-counting sort commands are listed in the Sorting section below.  The remaining options:
  Display shows the results after counting and any sorting,
  Date requests the date in each query, which only is useful if Dots is not used,
  Dots displays one dot per email, not requests or replies,
  Pause pauses after checking each email,
  Retain continues with any prior count rather than starting a new count.

The sorting options are available, but it is probably more straightforward to just count sender eddresses first then sort them and save them afterward.  Examine the count results in order to create Move list, White list, or Black list commands.  More than one or two gets burdensome, so they are best placed in a configuration file, as shown in the sections below.


Sorting HEAP-based buffers

IMAPTool can sort the contents of each HEAP-based data buffer.  The large HEAP-based reply buffer cannot be sorted, since it only breifly contains the reply to the last query.  The ten (10) HEAP-based transmit and receive buffers cannot be sorted, since each only contains a single recent query and its corresponding reply.
  _H   displays stats about all twentry-one (21) HEAP-based buffers,
  _H ?   displays the online help for the HEAP-based buffers,
  _H 11 Print   displays the contents of the first sTxRxPair buffer.

Notice that ten (10) of them have names beginning with H_ to their right.  These are the buffers which can be sorted.  Either the index of the HEAP structure (the number inside the square brackets) or its name can be use to specify which list to sort.  This feature is most useful when working with a sender eddress list.  To select the sender eddress list, any of H_Counter or 3, or H_Eddress or 4 will select the same data block.  All data buffers can be sorted alphabetically, not case sensitive by default, but case sensitivity may be enabled.  The sorting commands which apply to all ten (10) HEAP-based buffers:
  Alphabetize or Insensitive,
  Case or Sensitive changes that to a case-sensitive alphabetic sort,
  Debug which enables debug output while sorting,
  Pause which pauses after checking each block.

When sorting the eddresses counts, the eddresses found are kept in one HEAP-based list and the number of times each is encountered is kept in another.  Consequently, these sorting command options are only available when sorting this buffer pair:
  Count or Descending, sorts from highest count to lowest,
  Ascending alone also sorts by count, changing the order from least to most,
  Domain, to which Case can follow to modify it,
  TLD or Top, which sorts by Top Level Domain (e.g., .BIZ then .COM then .GOV then .NET)

Sorting by count refers to how many times each unique eddress is encountered.  This sort can be done in order of either decreasing count, the default, or increasing count.  Sorting by domain begins the sort at the '@' symbol, so, for example, sender@myemail.com would come before Sender@nextmail.jp, which would come before ATest@PanAm.com, since the sorting begins at the '@' symbol and is not case sensitive, by default.  Sorting by Top-Level-Domain means that all .COM come before all .NET, which come before all .ORG eddresses.

There is also an option to enable Debug output, which generates a LOT of text, and an option to Pause while sorting, and Print to display the results immediately after the sorting is complete.  Pressing Esc once while sorting causes the sort routine to abandon sorting immediately and return to the prompt, so the sort almost certainly be incomplete.

Use Sort ? to display help while online.


Save to disk

The ability to save the list of email senders is provided in order to be able to subsequently examine and selectively include eddresses gleaned from it into the configuration file.  This is the only list which can be written to disk, since all of the other lists are read in from the configuration file, so they are already on the disk.  For that reason, the Save command has no list specifier.  It syntax is:
  Save [options] [File:FileName]

Write and Disk are synonyms for the Save command keyword.  The options are for any sorting that is to be done prior to writing the file to disk.  If the file is already sorted into the desired order, all options can be safely skipped.  Refer to the sorting keywords or the online help for this command for the full list and details.

The  File:FileName  parameter is optional in issuing this command but a file name is eventually required, of course.  If supplied here, it must be the last thing on the line.  It can contain space(s) and even a drive and/or path; any trailing space(s) will be removed.  If it is not specified, it will be requested when it is needed, after sorting is complete, if one of the sort options was specified.


Print to console

This command is used to display the contents of a HEAP-based sHeapData[] buffer.  The syntax is:
  PR[INT] index
The index can be specified by any single buffer index (0 through 9) or by name.  Use the  _H  command to see the buffer names.  If a sender eddresses count has been done, then the buffer pair H_Counter (3) and H_Eddress (4) have both been populated, so both are printed and used together.

There are ten (10) other HEAP-based buffers, sTxRxPair[ 0 ] through sTxRxPair[ 0 ], the contents of which can be printed.  These buffers contain the most recent IMAP queries and corresponding replies.  Some examples of how to use them:
  _H  displays the status of all twenty-one (21) HEAP_based buffers,
  _H 11 Print  prints the buffer contents to which sTxRxPair[ 0 ] points,
  _H 12 Struct -  the '-' causes only the 16-BYTE structure of sTxRxPair[ 1 ] to be shown,
  _H 13  dumps the contents of structure sTxRxPair[ 2 ],
  _H 14 128
  _H 15 128 struct

If sTxRxPair[9], the second "large buffer" transaction buffer, has not been used,  _H 20 struct  it will show that all four (4) of its structure elements of sTxRxPair[9] have the value 0, which includes a NULL HEAP pointer.  The first eight (8) sTxRxPair structures are used to save the usual and smaller query and repliy pairs.  They are assigned in a round-robin order.  The last two (2) buffers sTxRxPair structures (8 and 9) are reserved for larger replies and are allocated as needed.  If all queries and replies are less than their common HEAP size assignment, set using  /H=### , then those two will still be unused, even after a many transactions.

Although hPtrReply is the first entry in the list generated by the  _H  command, it should nearly always show that it has no BYTEs.  This is the buffer into which all reply BYTEs are initially placed.  After the complete reply has been received, the matching query (already saved in an sTxRxPair[]) buffer) is located, and the reply is transferred to that buffer and removed from the hPtrReply buffer.


White list and black list

First, a word of caution: when processing emails, if any entry on the Black list is found, that email is deleted.  It is not moved to another folder.  There is no opportunity to recover it later.  Make sure that entries on this list are those which you just want gone.  The White list provides a way to shield specific entries from begin processed by the Black list.

Since these two commands have the same syntax, they are presented together.  Each command, or entry, should be placed on one line of the configuration file.  Each type is read into a HEAP-based buffer when IMAPTool starts.  The command syntax is:
  [/]W=string skip if the SUBJECT field has the string, e.g., /W=payroll, and
  [/]W=F:sender, skip if the FROM field has the string, e.g., /W=WestAmer
  [/]B=string delete if the SUBJECT field has the string, e.g., /B=cheap,
  [/]B=F:sender delete if the FROM field has the string, e.g, /B=Spotif

The  [/]W=  specifies a White list entry and  [/]B=  a Black list entry.  The  F:  after the = specifies that the FROM field is to be exampled.  If there is no F:, then the string is added to the H_WhiteSubject or H_BlackSubject block.  This is the most compact syntax, however, [/]W=S:, [/]W=Subj:, [/]W=Subject:, and [/]W=From: (and the /B= counterparts) are also understood and accepted.  The string comparisons will not be case-sensitive.  When placed in a configuration file, the leading '/' may be omitted.  An entry, or command, line can contain a space, but need not specify a complete string; the syntax and an example:
  W=F:sender
; Note: Blocks like this one signify .CFG (configuration) file contents
W=Bank Of Am       ; Leave emails containing this subject line in the INBOX
W=F:nkofamer       ; Also leave those contain this substring in the sender eddress in the INBOX

In the configuration file example shown, there is a semicolon and a comment after the string definition.  When a semicolon is found, the rest of the line is treated as a comment, so the command definition would be truncated at the semicolon.  Each line is also checked after that to see if it ends in a space; any space(s) is/are trimmed from the end of the line, so the only portion that is saved in the H_WhiteFrom block is "Bank Of Am", followed by a NULL.

These entries can occur in the configuration file in any order.  There can, of course, be many command entries of each of these types.  Each sender string does not need not be a complete eddress, but it can be a portion of one.  These aspects apply to the move list described below as well.

See the end of the next section for how to start processing the lists after creating them.


Move to folder lists

The move list provides a method of transferring emails from one folder to another.  The syntax of the configuration file entry:
  [/]M=sender,folder where a comma is the field separator
Again, the leading '/' may be omitted when the line is placed in a configuration file.  Some examples:
M=Smith,Family
M=Anthony Green,Friends            ; The sender portion may contain a space
M=ETrade,Financial/ETrade          ; The target folder may be deeper than the first level
M=Fidelity.Com,Financial/Fidelity
M=HomeSCADA.Com,Friends/Dave &- Joyce

If a folder has a space, include the space, but if it has an ampersand, use "&-" instead, so for example, the folder "Dave & Joyce" as a subfolder under the Friends parent folder would be correctly specified as shown above.

There must be no space after the sender field and the target folder field, only a comma as the field separator.  If a move list entry is encountered but the folder (or "mailbox") which it specifies does not yet exist, that destination folder will be created.

After successfully logging in, processing the list(s) that are defined is done with a command.  When the   >   prompt is shown, use this syntax:
 Mo[velist] [#1[:#2|-#2]] [Wh[itelist]] [Bl[acklist] [ALL] [F:Name]

The most terse forms are  MO ,  WH , and  BL , which can be in any order and are not case sensitive.  To process all emails in the INBOX, using all three (3) lists,  MO ALL ,  Wh All , or  BL ALL  could be used, omitting the range and folder name.  Only those lists selected are processed.  If the Move list is selected, it is always processed first.  If either or both White lists (subject and/or sender) are selected and they have entries, they are processed next.  Finally, the Black lists are processed, if either of them was specified and has entries.


Scripts

Scripts are a sequence of commands to be executed upon logging into the IMAP server.  This is especially useful if using the program to scan and remove unwanted emails (i.e., "spam") before logging into the email server to check email, particularly if logging in frequently.  Although script commands are accepted on the command line or in the environment, their use make the most sense when then are contained in the configuration file.  Here is an example of a script:
; /C=command specifies the command as it would be typed
/C=Count 1:999 Dots    ; No error if fewer than 999
/C=Save File:Raw.Txt
/Capture=F12           ; Non script command mixed in
/C=Save Alphabetize File:ByEddress.Txt
/C=Save Count File:ByCount.Txt
/C=Save Domain File:ByDomain.Txt
/C=Save TLD File:ByTLD.Txt
/C=Logout      ; Gracefully exit the program

END            ; Stop processing the .CFG file at this point
ColorQuery = 0xF0      This line would not even be read
 . . .

As shown in the example, comments may be included on the line containing a script command.  If any configuration statements which are not part of the script are placed in between script statements, it does not cause a problem executing the script.  This is because the configuration file is read completely and each script command is placed in a HEAP-based buffer (H_Command) in the order encountered before any attempt is even made to log into the IMAP server.  Actually, the environment is processed, the configuration file read, the command line processed, and the license validated before any Internet connection attempt is made, including resolving the host name to an IP address.  If the script does not end in a Logout command, it just ends by displaying the ">" prompt, waiting for the next command to be entered.

IMAPTool stops reading this file upon encountering the line which begins with End.  Any lines after that are, in effect, just comments.


Changing text color

IMAPTool saves the text color when the program starts, and if it ends normally, it restores the text color to that color on exit.  When it sends text to the console, it may change the text color to one of those shown below.  By default, an IMAP request (or query) is shown in bright green text and an IMAP reply is bright cyan.  These can be changed using specific configuration keywords.  All those which the program recognizes are listed below, in the configuration file syntax.
ColorCaptureToDisk  = 0xF0  ; BLACK          on BRIGHTWHITE
ColorDeleteMatching = 0x02  ; GREEN          on BLACK
ColorErrAlert       = 0x4F  ; BRIGHT WHITE   on RED
ColorErrAlertRev    = 0x7C  ; BRIGHT RED     on WHITE
ColorErrAlertRev2   = 0x8C  ; BRIGHT RED     on GREY
ColorFindMatching   = 0x0B  ; BRIGHT CYAN    on BLACK
ColorGetReply       = 0x4F  ; BRIGHT WHITE   on RED     while marking time, waiting for a reply
ColorHEAPDetails    = 0x70  ; BLACK          on WHITE
ColorHEAPPtrChange  = 0x0C  ; BRIGHT RED     on BLACK
ColorMoveRxToHEAP   = 0x89  ; BRIGHT BLUE    on GREY
ColorRequest        = 0x0A  ; BRIGHT GREEN   on BLACK   or "ColorQuery" may also be used
ColorReply          = 0x0B  ; BRIGHT CYAN    on BLACK
ColorScript         = 0xF2  ; GREEN          on BRIGHTWHITE
ColorSendToSocket   = 0x0D  ; BRIGHT MAGENTA on BLACK
ColorShowGRCTime    = 0x09  ; BRIGHT BLUE    on BLACK
ColorSocket         = 0x71  ; BLUE           on WHITE
ColorSocketError    = 0x0C  ; BRIGHT RED     on BLACK
ColorSort           = 0x03  ; CYAN           on BLACK
ColorUnexpectedRx   = 0x0E  ; BRIGHT YELLOW  on BLACK

To check how a color appears on your console screen, the system command Color ##, where ## is either a single or two (2) hexadecimal digits.  The 0x hexadecimal prefix above is used in the configuration file, but not when using the system Color command.  The decimal equivalent value can be used in the configuration file, but not in the syste command Color.  Use Color ? to obtain help with that system command.

Debugging options

The debug constants below are specified using the  /D#  syntax.  The program does not interpret the mnemonics in the first column, so these are not shown in a configuration file block.  In order to enable multiple debug options, combine the hex values shown, since they are saved as individual BITs in a single 32-BIT variable.  Note that  /DSet  enables the four (4) contants with the '*'.  Also, constants 2, 4, and 8 disable output, while nearly all others enable additional output.  As an example, to enable both the DumpSockReply (= 0x10) and DumpShowAddress (= 0x20) debug output options, any of  /D0x30,  /D=0x30,  /D48, or  /D=48  may be used.

OnStartAndStop0x00000001   *    Show details during program startup & shutdown
NoHorizontalRule0x00000002DO NOT show row of dashes between commands
HideSockQuery0x00000004DO NOT show each request sent
HideSockReply0x00000008DO NOT show each reply received
DumpSockReply0x00000010Display (dump) replies in debug format
DumpShowAddress   0x00000020   *Shows absolute memory address during dump
DumpOmitDash0x00000040Omits the '-' between BYTEs 7 & 8 during dump
CommandHandler0x00000080Show more details in the command handler
FoundResults0x00000100   *Show "found" strings in MoveWhiteBlack logic
CountPrintFrom0x00000200Show each "From:" string found while counting
CountDetails0x00000400Show comparisons while counting (verbose)
BlackListCheck0x00000800Show details while processing BlackList entries
MovePairsCheck0x00001000Show details while processing MoveList entries
WhiteListCheck0x00002000Show details while processing WhiteList entries
ShowIfMultiple0x00004000Display repeated eddresses and counts while counting
EMailDetails0x00008000   *Show received BYTE count and latency of each reply
HEAPDetails0x00010000Show HEAP allocation/re/deallocation details
StoreHEAPData0x00020000Show when Whitelist, Blacklist, or Movelist strings are added
PrintSendVerify0x00040000Output each time, not just on err
GetReply0x00080000Show info on every GetReply() call
Search0x00100000Show details while searching for text
ShowDeltaRxTime0x00200000Show time difference between receives
ShowExtKeypress0x00400000Decode and show extended key codes
ShowPassword0x00800000Display the actual password during logon
ShowProgress0x01000000Show send BYTE count, reply result and loops
ShowTime0x02000000Show clock time for each query and reply
FindMsgBuffer0x04000000Show sTxRxPair[] buffer search status and result
ConfigDetails0x08000000Show each line read from the configuration file
ReadFileCache0x10000000Show details while reading the configuration file
EncodeOrDecode0x20000000Show details during Base64, UTF7, UTF8 logic
TextColorLine0x40000000Show line number when changing text color

There are a few additional debug constants, specifically for OpenSSL.  Use the  /O#  syntax.  Since this is for debugging in the OpenSSL interface module, the key is the letter o, either uppercase or lowercase, not the number '0'.  Again, add values to select multiple options.

ShowQuery       0x00000001       Show each OSSL request sent
ShowReply0x00000002Show each OSSL reply received
DumpReply0x00000004Display (dump) OSSL replies in debug format
CallReturn0x00000008Show some OSSL routines' values on entry and exit
Connect0x00000010Show details while setting up the connection
Disconnect0x00000020Show details while tearing down the connection


OpenSSL Dynamically Linked Library Files

IMAPTool is configured to use TLS (Transport Layer Security) encryption, by default.  It can be instructed not to use it, however, most IMAP servers require that encryption be used.  IMAPTool uses OpenSSL to perform all of the TLS encryption and decryption tasks.  For users whose physical address is in the United States where encryption software may be freely distributed without requiring any export license, the option to also obtain the OpenSSL files required is provided on the Downloads page.  For users who are outside the U.S. or for those wanting to obtain the OpenSSL software independently, the information below should help.

OpenSSL v1.0.2u is the 32-bit version which was tested and was verified to be working correctly with IMAPTool.  It was obtained from https://indy.fulgan.com/SSL and the URL for the specific .ZIP file for this version is https://indy.fulgan.com/SSL/openssl-1.0.2u-i386-win32.zip.  This .ZIP file does NOT contain source code, but has the two (2) required DLLs, as well as four (4) other files, including the OpenSSL license.  OpenSSL source code is maintained at https://github.com/openssl/openssl.

The .ZIP file mentioned above contains both precompiled DLLs for Win32 as well as several other files, including a ReadMe.Txt.  That file contains this requirements line: "Indy 10.5.5+ (SVN Version or Delphi 2009 and newer)", but the only files that are actually required by them are these five (5) Windows® system files: advapi32.dll, gdi32.dll, kernel32.dll, user32.dll, and ws2_32.dll.  IMAPTool.Exe requires kernel32.dll, ws2_32.dll, libeay32.dll, and ssleay32.dll.  The last two listed are those contained in the OpenSSL .ZIP file.  Finally, for more information about OpenSSL, https://wiki.openssl.org/index.php/Binaries may prove helpful.


Configuration file example

With the exception of any "/D##" command, the configuration file is read (unless  END  terminates reading before reaching the end of the file) and the configuration contents are applied before any action is taken.  The first semicolon found which is not inside quotation marks is treated as the start of a comment.  That line is truncated at the semicolon, then any trailing spaces in the line that remains are also trimmed.  Any command line which starts with a semicolon is therefore ignored entirely.  All of the commands shown below, except scripts, may be specified in any order, although it makes sense to keep logically similar commands together.  Scripts are executed in the order which they occur, and, although they aren't required to occur in one block, it is less error-prone to keep them together.

; The syntax for specifying an IMAP server and port on which to connect:
;  /Shostname[:port] specifies the IMAP server; port is optional but concise
; To specify the port explicitly (i.e., not use :port above), the syntax is:
;  /Pport                  ; Example: /P993
; Example #1: when wanting to not use Transport Layer Security (TLS):
;  /Simap.host.com:143     ; 143 - IMAP port that does not initially use TLS
;  NoTLS
; Example #2:
;  /Simap.aol.com:993      ; Connect to AOL using TLS
; Example #3               ; All of the lines above are comments; this one is not:
/Simap.gmail.com:993       ; This is a live example

; Syntax used to specify the email account credentials:
;  /Ueddress@somewhere.com ; Email address (user name)
;  /Ppassword              ; Account password
; Either/both may be typed in after program starts if not specified here.
/Umyaddress@host.com       ; Obviously, the IMAP server will not like these
/Pmypassword               ;  since they are not your eddress or password

; These commands create a script; they are saved in the order listed below
;  and are executed in the same order:
/C=Select          ; Command #1 for an auto-executing script
/C=F6 1:10         ; Send "FETCH 1:10 (Body[Header.Fields (Date From Subject)])"
/C=_H              ; Show all HEAP buffers
/C=Sleep 10        ; Yield control to the O.S. for 10 seconds
/c=_H 3            ; "/c" is not case sensitive; each entire "/C" command shown
/c=F1 1:4          ;  in these examples is not case sensitive
/C=Move All 1:3    ; Begin processing the move list, white list, and black list
/C=Logout          ; If not specified, left at the ">" prompt, awaiting input

/Capture=SF12      ; Define Shift-F12 to toggle capture; see the note below
; /Capture=True    ; Enable capture before even attempting to connect
; /CaptureTime     ; Either of these can be added, but they will very likely
; /CaptureColor    ;  produce too much extra information

;   Commands for doing email filtering and removal
; 'B=' specifies a Blacklist entry (case insensitive search):
B=F:Apple.Com      ; "F:##" specifies a "From" field entry
B=F:ITunes.Com
B=F:ghostwrit      ; Catch either "ghostwriter" or "ghostwritten"
B=Vuitton
B=medica           ; Without the "F:", the subject field is selected
B=meds
B=enhanc           ; Catch "enhance", "enhanced", or "enhancing"
B=refinance
B=timeshare
B=gucci
B=F:Hertz.Com

; 'W' specifies a White list entry (either on the subject or with the "F:"
;  for the "from" field), which, when "White" is selected.  They are checked
;  after the move list and before either blacklist:
W=Payroll
W=F:Payroll

; 'M' sets a Move list entry (string in the "From:" field,destination folder)
M=Lewis@,Friends,Scott &- Mary
; Miscellaneous:
M=Adobe.Com,Miscellaneous/Adobe
; Online:
M=Amazon.Com,Online/Amazon

END
Anything on this line or after is not read due to the "END" command.

Capture function keys are defined using F1 though F12.  A prefix can include an 'A' for "Alt-", a 'C' for "Ctrl-", or 'S' for "Shift-".  To enable capture at startup, using /Capture=True, a toggle key must first be defined.  This was done with the /Capture=F12 above, since there should be some way of disabling capture other than just exiting the program.  Exiting the program closes the capture file.

A folder name in a move list entry can include a space or single quote, but not double-quotes.  An ampersand (&) in a folder name must be represented as "&-", as shown in the first move list entry above.  The header rows (comment rows with the category or folder name) aren't necessary; they just help in grouping and avoiding errors.


Notes

IMAPTool does not decode the body of any message, so it cannot execute any code contained in an email, should that email contain something that the email sender intended to execute in the client device.

Although IMAPTool is a 32-bit program, it should work on all Windows® versions from Win95 through Windows® 10.  It makes no Internet connection to HomeSCADA or SCADASupport.  It only communicates with the email server specified and a DNS server to resolve the IMAP host name into an IP address.  It does not make any change to the text-based configuration file; it only reads its contents.  It does not access the registry, but only uses the configuration file, to both make it easier to change and avoid inadvertant registry corruption.

Downloads page