org.apache.commons.net.smtp
public class SMTPClient extends SMTP
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 {@link org.apache.commons.net.smtp.SMTP#getReplyCode 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
{@link org.apache.commons.net.smtp.SMTPReply#SERVICE_NOT_AVAILABLE SMTPReply.SERVICE_NOT_AVAILABLE }
response to a command.
When that occurs, the method encountering that reply will throw
an {@link org.apache.commons.net.smtp.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
{@link org.apache.commons.net.smtp.SMTPConnectionClosedException}
, you must disconnect the connection with
{@link #disconnect disconnect() } to properly clean up the
system resources used by SMTPClient. Before disconnecting, you may check
the last reply code and text with
{@link org.apache.commons.net.smtp.SMTP#getReplyCode getReplyCode },
{@link org.apache.commons.net.smtp.SMTP#getReplyString getReplyString },
and
{@link org.apache.commons.net.smtp.SMTP#getReplyStrings 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 {@link org.apache.commons.net.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.
See Also: SMTP SimpleSMTPHeader RelayPath SMTPConnectionClosedException
Method Summary | |
---|---|
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 ({@link #sendMessageData sendMessageData })
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.
|
Parameters: path The forward relay path pointing to the recipient.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: address The recipient's email address.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
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;
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Returns: The system help string obtained from the server. null if the information could not be obtained.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: command The command on which to ask for help.
Returns: The command help string obtained from the server. null if the information could not be obtained.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: hostname The hostname with which to greet the SMTP server.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
You must not issue any commands to the SMTP server (i.e., call any (other methods) until you finish writing to the returned Writer instance and close it. The SMTP protocol uses the same stream for issuing commands as it does for returning results. Therefore the returned Writer actually writes directly to the SMTP connection. After you close the writer, you can execute new commands. If you do not follow these requirements your program will not work properly.
You can use the provided {@link org.apache.commons.net.smtp.SimpleSMTPHeader} class to construct a bare minimum header. To construct more complicated headers you should refer to RFC 822. When the Java Mail API is finalized, you will be able to use it to compose fully compliant Internet text messages. The DotTerminatedMessageWriter takes care of doubling line-leading dots and ending the message with a single dot upon closing, so all you have to worry about is writing the header and the message.
Upon closing the returned Writer, you need to call {@link #completePendingCommand completePendingCommand() } to finalize the transaction and verify its success or failure from the server reply.
Returns: A DotTerminatedMessageWriter to which the message (including header) can be written. Returns null if the command fails.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: message The short email message to send.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: sender The email address of the sender. recipient The email address of the recipient. message The short email message to send.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: sender The email address of the sender. recipients An array of recipient email addresses. message The short email message to send.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: path The reverse relay path pointing back to the sender.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: address The sender's email address.
Returns: True if successfully completed, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: username The username or email address to validate.
Returns: True if the username is valid, false if not.
Throws: SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.