SMTPClient

SMTPClient encapsulates all the functionality necessary to send files through an SMTP server. This class takes care of all low level details of interacting with an SMTP server and provides a convenient higher level interface. As with all classes derived from SocketClient , you must first connect to the server with connect before doing anything, and finally disconnect after you're completely finished interacting with the server. Then you need to check the SMTP reply code to see if the connection was successful. For example:

    try {
      int reply;
      client.connect("mail.foobar.com");
      System.out.print(client.getReplyString());

      // After connection attempt, you should check the reply code to verify
      // success.
      reply = client.getReplyCode();

      if(!SMTPReply.isPositiveCompletion(reply)) {
        client.disconnect();
        System.err.println("SMTP server refused connection.");
        System.exit(1);
      }

      // Do useful stuff here.
      ...
    } catch(IOException e) {
      if(client.isConnected()) {
        try {
          client.disconnect();
        } catch(IOException f) {
          // do nothing
        }
      }
      System.err.println("Could not connect to server.");
      e.printStackTrace();
      System.exit(1);
    }

Immediately after connecting is the only real time you need to check the reply code (because connect is of type void). The convention for all the SMTP command methods in SMTPClient is such that they either return a boolean value or some other value. The boolean methods return true on a successful completion reply from the SMTP server and false on a reply resulting in an error condition or failure. The methods returning a value other than boolean return a value containing the higher level data produced by the SMTP command, or null if a reply resulted in an error condition or failure. If you want to access the exact SMTP reply code causing a success or failure, you must call getReplyCode after a success or failure.

You should keep in mind that the SMTP server may choose to prematurely close a connection for various reasons. The SMTPClient class will detect a premature SMTP server connection closing when it receives a SMTPReply.SERVICE_NOT_AVAILABLE response to a command. When that occurs, the method encountering that reply will throw an SMTPConnectionClosedException . SMTPConectionClosedException is a subclass of IOException and therefore need not be caught separately, but if you are going to catch it separately, its catch block must appear before the more general IOException catch block. When you encounter an SMTPConnectionClosedException , you must disconnect the connection with disconnect() to properly clean up the system resources used by SMTPClient. Before disconnecting, you may check the last reply code and text with getReplyCode , getReplyString , and getReplyStrings.

Rather than list it separately for each method, we mention here that every method communicating with the server and throwing an IOException can also throw a MalformedServerReplyException , which is a subclass of IOException. A MalformedServerReplyException will be thrown when the reply received from the server deviates enough from the protocol specification that it cannot be interpreted in a useful manner despite attempts to be as lenient as possible.

At least one SMTPClient method ( sendMessage ) does not complete the entire sequence of SMTP commands to complete a transaction. These types of commands require some action by the programmer after the reception of a positive intermediate command. After the programmer's code completes its actions, it must call this method to receive the completion reply from the server and verify the success of the entire transaction.

For example,

 writer = client.sendMessage();
 if(writer == null) // failure
   return false;
 header =
  new SimpleSMTPHeader("foobar@foo.com", "foo@foobar.com", "Re: Foo");
 writer.write(header.toString());
 writer.write("This is just a test");
 writer.close();
 if(!client.completePendingCommand()) // failure
   return false;

boolean	addRecipient(RelayPath path) Add a recipient for a message using the SMTP RCPT command, specifying a forward relay path.
boolean	addRecipient(String address) Add a recipient for a message using the SMTP RCPT command, the recipient's email address.
boolean	completePendingCommand() At least one SMTPClient method ( sendMessage ) does not complete the entire sequence of SMTP commands to complete a transaction.
String	listHelp() Fetches the system help information from the server and returns the full string.
String	listHelp(String command) Fetches the help information for a given command from the server and returns the full string.
boolean	login(String hostname) Login to the SMTP server by sending the HELO command with the given hostname as an argument.
boolean	login() Login to the SMTP server by sending the HELO command with the client hostname as an argument.
boolean	logout() Logout of the SMTP server by sending the QUIT command.
boolean	reset() Aborts the current mail transaction, resetting all server stored sender, recipient, and mail data, cleaing all buffers and tables.
Writer	sendMessageData() Send the SMTP DATA command in preparation to send an email message.
boolean	sendNoOp() Sends a NOOP command to the SMTP server.
boolean	sendShortMessageData(String message) A convenience method for sending short messages.
boolean	sendSimpleMessage(String sender, String recipient, String message) A convenience method for a sending short email without having to explicitly set the sender and recipient(s).
boolean	sendSimpleMessage(String sender, String[] recipients, String message) A convenience method for a sending short email without having to explicitly set the sender and recipient(s).
boolean	setSender(RelayPath path) Set the sender of a message using the SMTP MAIL command, specifying a reverse relay path.
boolean	setSender(String address) Set the sender of a message using the SMTP MAIL command, specifying the sender's email address.
boolean	verify(String username) Verify that a username or email address is valid, i.e., that mail can be delivered to that mailbox on the server.

Class SMTPClient

Method Summary

Method Details

addRecipient

addRecipient

completePendingCommand

listHelp

listHelp

login

login

logout

reset

sendMessageData

sendNoOp

sendShortMessageData

sendSimpleMessage

sendSimpleMessage

setSender

setSender

verify