imapmail, pop3mail

manipulate mail messages on IMAP and POP3 mail servers 

Command


SYNOPSIS

imapmail server [-ADimS] [-u username] [-p password] [-f folder] [-c certfile] [-X auth_excl_list] [count | index [num] | rindex num | display num | delete num | recent | unseen ]

imapmail [-ADimS] [-u username] [-p password] [-f folder] [-c certfile] [-X auth_excl_list] server [count | index [num] | rindex num | display num | delete num | recent | unseen ]

pop3mail server [-ADimS] [-u username] [-p password] [-f folder] [-c certfile] [-X auth_excl_list] [count | index [num] | rindex num | display num | delete num | size]

pop3mail [-ADimS] [-u username] [-p password] [-f folder] [-c certfile] [-X auth_excl_list] server [count | index [num] | rindex num | display num | delete num] size]


DESCRIPTION

The imapmail and pop3mail utilities manipulate mail messages on IMAP and POP3 mail servers, respectively.

The server argument specifies the mail server on which you want to manipulate mail messages. This argument can either just be the name of the server itself or it can include the name of the user whose mailbox is to be read, in the form username@server. If the user name is a domain name you can specify it as either domain/user or domain\user.

In addition, these utilities use the .netrc file (see the .netrc reference page) in the same way as the rexec utility to eliminate the need to enter a user name and password each time.

Both the imapmail and pop3mail utilities support the following sub-commands that can be specified on the command line:

index [num

displays a line showing the number of messages in the specified folder in the user's mailbox, followed by a numbered list of messages (one per line) in that folder. The messages are displayed from oldest to newest.

If the optional num is specified, the num oldest messages are displayed. If num is a list (a series of message numbers separated by commas) or a range (a pair of message numbers separated by a hyphen), all messages in the list or range are displayed. In addition to single message numbers, a list can contain a range as one of its entries.

count 

displays the number of messages in the specified folder in the user's mailbox.

rindex [num

displays a line showing the number of messages in the specified folder in the user's mailbox, followed by a numbered list of messages (one per line) in that folder. The messages are displayed from newest to oldest.

If the optional num is specified, the num newest messages are displayed. If num is a list (a series of message numbers separated by commas) or a range (a pair of message numbers separated by a hyphen), all messages in the list or range are displayed. In addition to single message numbers, a list can contain a range as one of its entries.

delete num 

deletes the numth message in the folder. The numbering of messages is as returned by the index command. If num is a list (a series of message numbers separated by commas) or a range (a pair of message numbers separated by a hyphen), all messages in the list or range are deleted. In addition to single message numbers, a list can contain a range as one of its entries. After all messages specified by num have been deleted, the remaining messages are renumbered. Before performing any other operations, you should issue a new index command to see the new numbering.

display num 

displays the numth message in the folder. The numbering of messages is as returned by the index command. If num is a list (a series of message numbers separated by commas) or a range (a pair of message numbers separated by a hyphen), all messages in the list or range are displayed. In addition to single message numbers, a list can contain a range as one of its entries.

The imapmail utility also supports the following additional sub-commands:

recent 

displays the number of messages added to the folder since it was accessed.

unseen 

displays the message number of the first unread message in the folder.

The pop3mail utility also supports the following additional sub-command:

size 

displays the size of the mailbox (or folder, if -f is specified).

Note:

These utilities assume that only one user is deleting messages from a mailbox folder at a time. If more than one user is deleting messages from the same mailbox folder, the numbers returned by the last index command may no longer be correct, and a user could end up deleting or displaying the wrong message.

When no sub-command is specified on the command line, imapmail and pop3mail behave as though index was specified.

Options

-A 

enables the passing of your current login credentials to the server (see Authentication below). If authentication fails (possibly, because either the client or server does not login credential passing), the user is prompted to provide a password.

-c certfile 

turns on SSL support and uses the specified certfile as the certificate authortity file.

-D 

turns on debugging mode.

-f folder 

specifies the mail folder that contains the messages to be manipulated (for example, inbox).

If no folder is specified, inbox is used by default.

-i 

ignores SSL security errors.

-m 

displays messages in the mbox format used by mailx. For example, you could use this option in a script that gets e-mail from a server and appends it to a mbox file that could be used with mailx.

-p password 

specifies the password to be used with username when accessing that user's mailbox on the server.

-S 

turns on SSL support using the default certificate authority file ROOTDIR/etc/openssl/cert.pem. This file must be populated before openssl will initialize. It is not provided by the PTC MKS Toolkit installation, rather a script ROOTDIR/etc/openssl/mkcabundle.pl is provided to populate the file with a sample set of certificates dynamically downloaded from the mozilla trusted certificates list. You may of course choose to provide your own list of trusted root certificates.

-u username 

specifies the name of the user whose mailbox on the server you want to access.

Alternatively, you can specify the user name as part of the server argument as described in the DESCRIPTION section.

Note:

Not all authentication mechanisms understand domain names. For those that do, you can specify username as domain/user or domain\user. However, for those that do not (such as CRAM-MD5), the domain name should not be included.

-X auth_excl_list 

specifies an authentication exclusion list (auth_excl_list). auth_excl_list is a comma-separated list of authentication mechanisms to ignore when attempting authentication. This list can contain any of the authentication mechanisms listed under Authentication below and is case insensitive.

It is recommended that auth_excl_list be placed within double quotes to ensure the command is always correctly interpreted by the shell or command interpreter being used.

Authentication

When the imapmail and pop3mail utilities attempt to connect to a server, the following steps are performed:

  1. imapmail (or pop3mail) attempts to connect using the user name and password specified with -u and -p (prompting for a password, if no -p is given and login credential passing is disabled) by cycling through various authentication mechanisms until connection is acheived.

  2. When login credential passing is enabled (either with -A or by setting the TK_ENABLE_CREDENTIAL_PASSING variable) and -u is specified, imapmail (or pop3mail) passes that user name to SSPI and lets Windows determine the appropriate password and cycles through various authentication mechanisms until the connection is achieved.

  3. When login credential passing is enabled and no user name is specified with -u, imapmail (or pop3mail) uses various methods to determine the user name depending on the authentication mechanism being attempted. For example, with SSPI mechanisms, no credentials are passed and Windows determines what user name should be used while with CRAM-MD5 or LOGIN, the current logged in user name is used (along with the domain if necessary).

Normally, login credential passing is disabled for the imapmail and pop3mail utilities. However, by setting the environment variable TK_ENABLE_CREDENTIAL_PASSING or by specifying the -A option on the command line, you can enable its use.

The following authentication mechanisms are supported for imapmail and pop3mail:

APOP 

Is a POP3-specific authentication mechanism that uses a MD5 checksum (similar to that generated by the md5sum utility) of a unique timestamp and a shared secret string (known only to the client and server). As long as the checksum is correct, the authentication succeeds. This mechanism is used only by pop3mail and not imapmail.

CRAM-MD5 

Is similar to APOP (but used by both pop3mail and imapmail) but instead of the shared secret string being transmitted as part of the checksum, it is used as a key to create a keyed MD5 checksum. With this mechanism, the shared secret string does not need to be stored as clear text on the server and, thus, is more secure.

LOGIN 

Is a not particularly secure authentication method that uses primarily clear text to transmit the user name and password. This is similar to the BASIC authentication method used by the web utility.

NTLM 

Is an authentication mechanism used by Windows, particularly as a integrated single sign-on (SSO) mechanism. It uses a challenge-response dialog between the client and server to allow the client to prove its identity without actually sending a password.


ENVIRONMENT VARIABLES

TK_ENABLE_CREDENTIAL_PASSING 

When set, enables the passing of your current login credentials to the server.


DIAGNOSTICS

Possible exit status values are:

0 

Successful completion.

1 

An error occurred.

2 

A usage error occurred.


PORTABILITY

Windows 7. Windows Server 2008 R2. Windows 8. Windows Server 2012. Windows 10. Windows Server 2016.


AVAILABILITY

PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Commands:
$%rootdir;/etc/openssl/mkcabundle.pl, mailx, rexec

File Formats:
netrc


PTC MKS Toolkit 10.1 Documentation Build 15.