Introduction
Regardless of if you work as a sysadmin, in a help desk or anywhere in between, it’s very handy to sometimes be able to communicate directly with e-mail servers when troubleshooting. That is, without having to go though a desktop application. I often times use the commands listed under the IMAP section when troubleshooting for YippieMove.
This kind of troubleshooting is fairly simple (at least if you’re on a Mac OS X/Linux/UNIX machine). Before we get started with the actual commands, there are a few tools you should be familiar with (in addition to the e-mail fundamentals, ie. POP3/IMAP/SMTP).
The first tool is Telnet. On Mac OS X (and other UNIXish platforms) you launch Telnet from a terminal (Mac OS X: /Applications/Utilities/Terminal.app). On recent versions of Windows (XP and later IIRC), you launch Telnet using the command line (Start -> Run -> cmd). The syntax for Telnet is very straight forward (and it’s the same on all platforms). Just type ‘telnet’ followed by the server, then a space and the port number.
The second tool is OpenSSL. On Mac OS X (and other UNIXish platforms) this works the same way as Telnet. On Windows however, you need to install it first, as it is not bundled with the system. Fortunately, the blog ‘Dave on Software’ put together a simple guide on how to do this (using Cygwin). The syntax for OpenSSL is not as straight forward as for Telnet. The syntax is as follows: ‘openssl s_client -connect’ followed by the server address, a colon (no space) and the port number.
An open IMAPs connection to Gmail
Troubleshooting IMAP
IMAP is the most sophisticated of the widely used email protocols. Contrary to POP3, the server permanently holds the email messages, which makes it a lot more extensive than POP3 (which was designed to only temporarily hold messages).
Connecting to an IMAP server
The first thing you need to do in order to connect to the IMAP is to find out whether the server you are connecting to is using SSL or not. If the server is not using SSL, the server is most likely listening on port 143 and if it is using SSL the server is most likely listening on port 993.
To connect to a server that does not use SSL, you simply issue the following command:
telnet mail.example.com 143
If your server is using SSL, then you issue the following command:
openssl s_client -connect mail.example.com:993
If you’re having trouble with the above command, try the following:
openssl s_client -crlf -connect mail.example.com:993
Logging in
Once you have connected to the server, the commands are the same regardless of if you used openssl or telnet. To log in, you simply type as follows:
. LOGIN username@example.com password
Please note that depending on how the server is configured, the username might be either ‘username’ or ‘username@example.com’. Also, the period (.) in the beginning is not a typo.
Logging out
To terminate your connection to the IMAP server, simply type:
. LOGOUT
Other useful commands
List all IMAP folders
. LIST "" "*"
Create a folder
. CREATE yournewfolder
Rename a folder
. RENAME yournewfolder someothername
Delete a folder
. DELETE someothername
Combo: Download a message
In this combo, I’ll walk you trough the process of downloading a message from the folder INBOX.
. SELECT INBOX
. FETCH 1:20 flags
This part fetches the message flags of the messages in the range 1-20.
. FETCH 5 rfc822.header rfc822.text
This part fetches both the header and the content of the message with the message ID number 5 (you could also do ‘FETCH 5 rfc822′, as it is the same thing as specifying both header and text).
For more IMAP commands, please visit Bob Peer’s blog. If you really want to dive into the juicy IMAP details, please visit read RFC3501.
Troubleshooting POP3
Connecting to a POP3 server is very similar to connecting to an IMAP server. Also similar to IMAP is that there are two types of servers: SSL and non-SSL. For POP3, most non-SSL server are listening on port 110, while SSL servers are running on port 995.
An open POP3 connection to FastMail.FM
Connecting to a POP3 server
To connect to a non-SSL server, simply run
telnet mail.example.com 110
To connect to an SSL server, run:
openssl s_client -connect mail.example.com:995
Logging in
Logging into a POP3 server is very straight forward. Simply issue the following commands
USER username
PASS password
Logging out
To log out of a POP3 server, just type:
QUIT
Other useful commands
To get get the account status, issue the following commands. It will return something like “+OK 2 320″, which means there are two new messages with the total size of 320 octets.
STAT
If you want to receive more extensive information than the ‘STAT’ command, you can issue the ‘LIST’ command, which will give you the same information as the ‘STAT’ command, but also a list of the messages (and the respective size).
LIST
Download a message. In order to use this command, you need to combine it with a message number (as you can get from the LIST command).
RETR 1
Delete a message. The delete command uses the same syntax as the ‘RETR’ command. Just type ‘DELE’ followed by the message number.
DELE 1
Combo: Download a message
In the following example, I’ll go through the task of downloading a message from the POP3 server.
LIST
Pick a message number (eg. 5)
RETR 5
For more information and commands, please see RFC1939.
Troubleshooting SMTP
Contrary to IMAP and POP3, SMTP is not used for storing emails. It is used for transporting emails. Therefore, regardless if you use POP3, IMAP or even some other proprietary storage system such as Exchange (MAPI) to access your emails, SMTP is used for both sending and receiving emails.
Connecting to an SMTP server
Connecting to an SMTP server is a bit more difficult than to connect to a POP3 or IMAP server. Moreover, instead of two common port numbers, there are three for SMTP. These ports are 25 (plain text), 465 (SSL) and 587 (STARTTLS). Due to security reasons, many modern email providers have phased out port 25 and instead switched over entirely to one of the two latter ports (or both).
Depending on the port number of the server you’re connecting to, pick the most suitable command below:
telnet smtp.example.com 25
openssl s_client -crlf -connect smtp.example.com:465
openssl s_client -starttls smtp -crlf -connect smtp.example.com:587
An open SMTP connection to Gmail
Introduce yourself
Part of the SMTP protocol is to introduce yourself (as it is meant for server-to-server introduction). To introduce yourself to the server, simply run:
HELO mycomputer.mydomain.com
Note: depending on how the server is configured, this may or may not be important. If you’re just trying to see if a set of credentials are valid, it doesn’t matter what you put in the HELO string.
Logging in
Some SMTP servers are not configured to require you to authenticate before logging in. You often find this kind of configuration on SMTP server that are restricted to be either physically wired to the network or which require a VPN to access the server. To prevent spam, most public servers requires you to log in before sending messages.
Authentication with a SMTP server is a bit difficult, as it requires you to send your username and password encoded in base64. If you’re on a Mac OS X or UNIXish machine, you’re likely to have Perl (and MIME::Base64) installed. In that case, you can generate this string with the following command:
perl -MMIME::Base64 -e 'print encode_base64("\000user\@example.com\000password")'
If you’re do not have Perl installed, you should be able to use this page to convert your credentials to a Base64 string (untested).
Once you have generated a Base64 string containing your credentials, you can use the following command in your SMTP session:
AUTH PLAIN your-string
Sending a message
Sending a message is pretty straight forward. In the snippet below, we send a message to ‘foobar@example.com’ from ‘you@example.com’.
MAIL FROM
RCPT TO
DATA
Subject: Hi Foobar
Dear Foobar,
If you can read this message, please let me know.
.
The blank line between ‘Subject’ and ‘Dear Foobar,’ must be there, as it separates the header from the message body. Also, the final period (.) is used to end the message.
Logging out
To close the connection to the SMTP server, just type:
quit
For more information about the SMTP protocol, please see RFC822 and RFC1123.