Build Your Own Java-Based Email Programs

Like this article? We recommend

Java 2 by Example, 2nd Edition

Learn More Buy

Like this article? We recommend

Like this article? We recommend 

Java 2 by Example, 2nd Edition

Learn More Buy

Sending an Email Message

Internet-based email messages are typically sent to recipients by way of the SMTP network protocol. According to SMTP, when an email program needs to send an email message, that program establishes a two-way transmission channel (by way of sockets) with a primary SMTP server program that is always running on some accessible host, such as your Internet Service Provider's (ISP's) host. The primary SMTP server program might be the email message's ultimate destination, or the primary SMTP server program might be an intermediary to another SMTP server program (on another host) that serves as the ultimate destination. Regardless, once the email and primary SMTP server programs have established a two-way transmission channel, the email program issues a sequence of ASCII-based commands to the primary SMTP server program, and the primary SMTP server program replies to each command with an ASCII-based response message indicating success or failure.

Assuming success, those commands result in an email message being sent from the email program to the primary SMTP server program, which might forward that email message to another SMTP server program (if the email message's address so indicates). If the email message is destined for a mailbox on the primary SMTP server program's host, the primary SMTP server program stores that email message in its associated email database. However, if the email message is destined for a mailbox on another host, the other host's SMTP server program stores that email message in its associated email database. Figure 2 provides an illustration of this SMTP model.

Figure 2 The SMTP model for sending email messages. Sockets appear as green boxes.

SMTP recognizes a variety of commands that email programs can use to communicate with SMTP server programs. Some commands take arguments and other commands take no arguments, but each command must end with a carriage-return character followed by a newline character. Six commonly used commands are HELO, MAIL, RCPT, DATA, RSET, and QUIT.

The previous ordering of the six commonly used SMTP commands is not an accident. Apart from RSET, the commands must be entered in their specified order because an SMTP server program is a state-based program. For each email program that establishes a two-way transmission channel, the SMTP server program maintains state on the current email message transaction with that email program (to keep track of its place in that transaction).

When an email program successfully connects its socket to an SMTP server program's server socket, the SMTP server program sends an initial message to the email program. That message consists of a three-digit reply code and a text message identifying the SMTP server program. The reply code, which is located at the beginning of every SMTP server program response message, identifies success or failure and is used by email programs to automate their email message transactions with SMTP server programs. By contrast, the text message provides meaningful information to a user. An email program must check the reply code to determine its next course of action, but it may ignore the text message if it is not deemed to be relevant (such as the initial message).

After receiving the initial message, an email program begins its email message transaction by sending the HELO command. HELO identifies an email program to an SMTP server program and takes an argument that identifies the SMTP server program's host's domain name. In response, the SMTP server program performs whatever initialization is necessary to set itself in an initial state for taking part in an email message transaction with the email program, and it typically sends a success response message back to the email program. The success response message begins with reply code 250 and continues with a greeting message.

Following HELO, an email program sends the MAIL command. MAIL identifies the sender to the SMTP server program and takes the argument FROM: and one email message address. If the SMTP server program has no trouble parsing the email message address, it typically returns a response message beginning with reply code 250. Otherwise, the response message begins with another code that identifies the reason for the failure.

Following MAIL, an email program sends the RCPT command. RCPT identifies a single recipient to the SMTP server program. That command takes the argument TO: and one email message address. If the SMTP server program has no trouble parsing the address, it typically returns a response message beginning with reply code 250. Otherwise, the response message begins with a different reply code that identifies the reason for the failure. You can specify multiple RCPT commands to address multiple recipients.

At this point, the email program needs to send the email message. It accomplishes that task by sending the DATA command (which takes no arguments), receiving a positive response message, sending each email message line, and sending a line that consists of a single-period character after the last email message line. After that, the email program waits for a response message to find out whether the email message was successfully received by the SMTP server program. After successfully sending the email message, the email program can choose to abort that message and the email transaction by sending the no-argument RSET command.

Finally, when the time comes to disconnect its transmission channel with the SMTP server program, the email program sends the no-argument QUIT command.

To help you understand SMTP-based email transactions, I wrote a command line–based program called SMTPDemo. When run, that program attempts to connect to my ISP's SMTP server program on standard port number 25. Although you should not need to change 25 (because that number is standard for an SMTP server program port), you will need to change mail.gatewest.net to the domain name of your ISP's host (so that the program will work for you) before compiling SMTPDemo's source code. Listing 1 presents that source code.

Listing 1: SMTPDemo.java

// SMTPDemo.java

import java.io.*;
import java.net.*;

class SMTPDemo
{
  public static void main (String [] args)
  {
   String SMTPServer = "mail.gatewest.net";
   int SMTPPort = 25;

   Socket client = null;

   try
   {
     // Attempt to create a client socket connected to the SMTP 
     // server.
     // program.

     client = new Socket (SMTPServer, SMTPPort);

     // Create a buffered reader for line-oriented reading from the
     // standard input device.

     BufferedReader stdin;
     stdin = new BufferedReader (new InputStreamReader (System.in));

     // Create a buffered reader for line-oriented reading from the
     // socket.

     InputStream is = client.getInputStream ();
     BufferedReader sockin;
     sockin = new BufferedReader (new InputStreamReader (is));

     // Create a print writer for line-oriented writing to the 
     // socket.

     OutputStream os = client.getOutputStream ();
     PrintWriter sockout;
     sockout = new PrintWriter (os, true); // true for auto-flush

     // Display SMTP greeting from SMTP server program.

     System.out.println ("S:" + sockin.readLine ());

     while (true)
     {
      // Display a client prompt.

      System.out.print ("C:");

      // Read a command string from the standard input device.

      String cmd = stdin.readLine ();

      // Write the command string to the SMTP server program.

      sockout.println (cmd);

      // Read a reply string from the SMTP server program.

      String reply = sockin.readLine ();

      // Display the first line of this reply string.

      System.out.println ("S:" + reply);

      // If the DATA command was entered and it succeeded, keep
      // writing all lines until a line is detected that begins
      // with a . character. These lines constitute an email
      // message.

      if (cmd.toLowerCase ().startsWith ("data") &&
        reply.substring (0, 3).equals ("354"))
      {
        do
        {
          cmd = stdin.readLine ();

          if (cmd != null && cmd.length () > 1 &&
            cmd.charAt (0) == '.')
            cmd = "."; // Must be no chars after . char.

          sockout.println (cmd);

          if (cmd.equals ("."))
            break;
        }
        while (true);

        // Read a reply string from the SMTP server program.

        reply = sockin.readLine ();

        // Display the first line of this reply string.

        System.out.println ("S:" + reply);

        continue;
      }

      // If the QUIT command was entered, quit.

      if (cmd.toLowerCase ().startsWith ("quit"))
        break;
     }
   }
   catch (IOException e)
   {
     System.out.println (e.toString ());
   }
   finally
   {
     try
     {
      // Attempt to close the client socket.

      if (client != null)
        client.close ();
     }
     catch (IOException e)
     {
     }
   }
  }
}

After you replace mail.gatewest.net with your ISP's hostname and compile SMTPDemo's source code, type java SMTPDemo. Carry out the following exercise, and you will see similar output:

The following exercise's output is from a sample session between myself (C:) and my ISP's SMTP server program (S:).

S:220 kynes.gatewest.net ESMTP Debian SendMail 8.12.1/8.12.0.
Beta19/Debian
8.12.0.Beta19; Sat, 2 Mar 2002 16:38:10 -0600

This initial message was sent from my ISP's Linux-based SendMail SMTP server program to SMTPDemo.

C:helo gatewest.net
S:250 kynes.gatewest.net Hello h139-142-224-80.gtcust.grouptelecom.net 
[139.142.224.80], pleased to meet you

I began the email message transaction by typing helo gatewest.net, where gatewest.net identifies my ISP's domain name. SendMail sent a greeting message, beginning with reply code 250, as its response.

C:mail from: <jeff@javajeff.com>
S:250 2.1.0 <jeff@javajeff.com>... Sender ok

I identified myself as the sender of the email message and was rewarded with a success response. (Angle brackets are optional.)

C:rcpt to: <jeff@javajeff.com>
S:250 2.1.5 <jeff@javajeff.com>... Recipient ok

I also identified myself as the email message's recipient so that I would not bother anyone else during my test. Once again, I received a success response.

C:data
S:354 Enter mail, end with "." on a line by itself
Subject: Test Email
This is my email message.
.
S:250 2.0.0 g22McAxW027265 Message accepted for delivery

I next specified the actual message by issuing the DATA command. After receiving a success response, I specified the message's subject and a single-line message. Note the period character on a line by itself. That character indicates the end of the message and is not part of the message. Also note the response. That response includes a message ID value of g22McAxW027265. SendMail includes that message ID value as part of the stored/forwarded email message, to uniquely identify email messages.

C:quit
S:221 2.0.0 kynes.gatewest.net closing connection

After sending the email message, there was nothing else to do, so I terminated my connection with the SendMail SMTP server program. Note the 221 reply code. The leftmost 2 indicates a positive completion, the middle 2 indicates the transmission channel (or connection), and the rightmost 1 indicates that the connection is closed.

Look carefully at SMTPDemo's output, and you'll find the Subject: header appearing as the first DATA line. That header identifies the subject of the email message, and its value typically appears in the subject portion of a receiving email program's GUI-based message list. If the From:, Sender:, Reply-To:, To:, and Cc: headers were also specified, they would appear as part of the data sent to the SMTP server program via the DATA command. Furthermore, as Subject: shows, each header would appear ahead of any nonheader content. The following paragraphs describe how a receiving email program uses the From:, Sender:, Reply-To:, To:, and Cc: headers' mailbox values.

The receiving email program displays From:'s mailbox values in the from portion of its message list. Furthermore, that program places those values (if no Reply-To: header was passed) in a new To: header when that program's user replies to the email message. If a From: header is not specified, an SMTP server program will probably generate a default From: header, using the email address from the MAIL command, before storing or forwarding that email message.

The receiving email program will probably ignore the Sender: header because replies are not (typically) sent to the sender. To ensure consistency between the email address specified as part of the MAIL command and the Sender: header, a sending email program could retrieve Sender:'s email address from a properties file and pass that value as an argument to MAIL.

The receiving email program places Reply-To:'s mailbox values in a new To: header when the user chooses to reply to an email message.

The receiving email program places To:'s mailbox values (along with Reply-To:'s mailbox values, if Reply-To: is present) in a new To: header when the user selects a reply-all function in the email program. To ensure consistency between the email addresses specified as part of RCPT commands and the To: header, a sending email program could take To:'s email addresses and pass each address as an argument to a RCPT command. If To: is not passed, the receiving email program does not disclose the RCPT addresses.

Finally, the receiving email program places Cc:'s mailbox values in a new Cc: header when the user selects a reply-all function in the email program.

Earlier, I discussed the attachment concept. You might wonder how to use SMTPDemo to send an attachment. To find out, run SMTPDemo and enter the following text (but use your own email address.) Use your favorite email program to retrieve the email message.

helo gatewest.net
mail from: jeff@javajeff.com
rcpt to: jeff@javajeff.com
data
Subject: Attachment Demo
Content-Type: multipart/mixed; boundary="***"

--***
Content-Type: text/plain; charset="iso-8859-1"

This message has an attachment.

--***

Content-Type: text/plain; name="file.txt"

Attachment text.

--***--
quit