bdat command, data chunking, and DSN. For more information, see Determining ESMTP Support.
During a single SMTP session, the client can send multiple unrelated, independently addressed messages. Because of this, the SMTP client can increase efficiency by batching messages and sending them together using pipelining. For more information, see Pipelining Commands.
The SMTP server waits for SMTP messages on the "well-known" TCP port 25. Many mail applications allow the user to specify a different port.
For a table of SDK-supported SMTP protocol commands, see Supported SMTP Internet Protocol Commands. For detailed information about SMTP, consult one of the RFCs listed, with links, in SMTP RFCs.
[Top]
| Step |
Section with details
|
|
|
|
Determine Extended SMTP (ESMTP)
|
|
|
|
| |
|---|
| Code |
Text of Response
|
|
|
|
|
|
|
| <domain> servers not available, closing transmission channel
|
|
|
|
|
|
|
|
|
|
|
|
| |
|---|
| Digit 1 | Meaning |
1yz | |
2yz | |
3yz | |
4yz | |
5yz |
netscape.messaging.smtp.ISMTPSink. Interface for the SMTP response sink. See Creating a Response Sink.netscape.messaging.smtp.SMTPClient. Represents the SMTP client. See Creating a Client.netscape.messaging.smtp.SMTPSink. Convenience implementation of the ISMTPSink interface. See Creating a Response Sink.netscape.messaging.smtp.SMTPException. Exception thrown when an SMTP API error condition is detected by the Messaging Access SDK. Extends IOException.netscape.messaging.smtp.SMTPServerException. Exception thrown from the error callback on the response sink when the server sends an error. Extends IOException and SMTPException. ISMTPSink interface contains callbacks for each client call. The client's processResponses method invokes the interface method that corresponds to the client call. Methods with multi-line responses map to more than one callback. The second callback provides a notification that the operation is complete.
If a server error occurs, the error callback is invoked.
Table 2.3 shows which SMTP methods are mapped to callbacks in the ISMTPSink interface. Table 2.4 shows methods that do not map to callbacks.
Table 2.3 Methods with Callbacks
| Methods Without Callbacks |
disconnect setChunkSize free setPipelining get_option setResponseSink initialize setTimeout processResponses set_option |
|---|
ISMTPSink interface. The response sink contains the callback methods for the SMTP client. For general information about the response sink, see "SDK Sink Classes for Java."
The ISMTPSink interface contains callbacks for each client call. You must implement this interface in order to use the SMTP client object. The constructor for the SMTPClient class takes an ISMTPSink object as a parameter.
To create your own response sink class, you can implement the ISMTPSink interface, using this syntax:
public class newSMTPSink extends ObjectAs a convenience, the Messaging SDK provides the
implements ISMTPSink
SMTPSink class, which implements the ISMTPSink interface. SMTPSink implements all the interfaces in ISMTPSink. By default, the implementation does nothing, except provide the error callback, which throws an exception. You can save a step by extending this class, using this syntax:
public class newSMTPSink extends SMTPSink{
}
The following section of code creates a response sink.
SMTPSink l_smtpSink;
l_smtpSink = new SMTPSink();After you create the response sink, the next step is Creating a Client. [Top]
SMTPClient object to communicate with the server. To create the SMTPClient object and set the response sink for the client's use, call the SMTPClient.SMTPClient class constructor, which takes an existing response sink. Use this syntax:
public SMTPClient(ISMTPSink in_sink)The following section of code creates a client.
/* Create sink first, as described in Creating a Response Sink */
SMTPClient l_client;
SMTPSink l_smtpSink;
l_client = new SMTPClient( l_smtpSink );After you initialize the client, the next step is Connecting to a Server. [Top]
SMTPClient.connect methods, depending on whether or not you want to specify the connection port. The SDK methods perform some error-checking.
To connect to the server using the default port for the SMTP protocol (port 25), use this form of connect and supply the identifier of the server:
public synchronized void connect(String in_server) throws IOExceptionTo specify the server port to use for the server connection, use the other form of
connect:
public synchronized void connect(String in_server,On connecting, the server sends a greeting message to client. The client responds by identifying itself with the EHLO command.
int in_port) throws IOException
NOTE: For this method's callback mapping, see SMTP Callback Mapping. §The following section of code connects the client to the server.
/* After Creating a Response Sink and Creating a Client */
l_client.connect( "smtpserver.com" );
l_client.processResponses();During the connect process, you can enable pipelining if your server supports it. See Pipelining Commands. To find out which extensions are supported by the server, see Determining ESMTP Support. After connecting to the server, the next step is Setting the Mailer To disconnect the client from the server, and close the socket connection, use this
SMTPClient class method.
public synchronized void disconnect() throws IOExceptionYou could use this function as part of a Cancel operation while retrieving a message. Remember that you do not call
processResponses after disconnect. If an input or output error occurs, the method throws an IOException.
[Top]SMTPClient.ehlo method. This method returns a multiline message listing the Extended SMTP (ESMTP) features, such as pipelining or DSN, that the server supports. This is similar to the functionality of the IMAP4Client.capability command. Use this syntax:
public synchronized void ehlo(String in_domain)This method calls the EHLO SMTP protocol command, which can be issued in any session state, but is usually issued after connecting to the server. In Messaging Server 3.5, the developer must determine ESMTP support; in Messaging Server 4.0, this is optional.
throws IOException
NOTE: For this method's callback mapping, see SMTP Callback Mapping. §The following section of code finds out which Extended SMTP (ESMTP) features the server supports.
/* After Connecting to a Server */
l_client.ehlo( "yourdomain.com" );
l_client.processResponses();You can enable pipelining if your server supports this extension. See Pipelining Commands. [Top]
SMTPClient.processResponses method is called, if the internal storage area is full, or if a method that cannot be pipelined is issued.
You can enable pipelining anywhere, but it may make sense to do this after invoking the SMTPClient.ehlo method. Pipelining may then be enabled if the server supports it. If not, the way the network works does not change. The ehlo callback indicates whether pipelining is supported.
Use this syntax to attempt to enable pipelining:
public synchronized void setPipelining(The
boolean in_enablePipelining)
throws SMTPException
in_enablePipelining parameter is a Boolean value that tells the server to attempt to enable pipelining. The method throws an SMTPException if PIPELINING is not supported by the server. This method sends the PIPELINING SMTP protocol command.
NOTE: For this method's callback mapping, see SMTP Callback Mapping. §Some methods continue to add to the pipelining list. These are
SMTPClient.bdat, SMTPClient.mailFrom, SMTPClient.rcptTo, and SMTPClient.send. Calling any other method causes the methods on the pipelining list to begin executing.
For example, you could call mailFrom, followed by one or more calls to rcptTo. These methods are added to the pipelining list and are not executed. If you then call another method, such as noop, the commands are sent to the server.
For details about using pipelining, refer to RFC 1854,"SMTP Service Extension for Command Pipelining."
[Top]in_esmtpParams parameter. Use the SMTPClient.mailFrom method:
public synchronized void mailFrom(String in_reverseAddress,This method identifies the sender and provides the sender's fully qualified domain name in the
String in_esmtpParams)
throws IOException
in_reverseAddress parameter. It sends the MAIL FROM SMTP protocol command. If an I/O error occurs, the method throws an IOException.
NOTE: For this method's callback mapping, see SMTP Callback Mapping. §The following section of code sets the mailer.
/* After Connecting to a Server */
SMTPClient l_client;
l_client.mailFrom( "sender@netscape.com", null );
l_client.processResponses();After you set the mailer, the next step is Setting the Recipient. [Top]
SMTPClient class method:
public synchronized void rcptTo(String in_forwardAddress,This method sets a single recipient, so you must call it again for each recipient of a message. The
String in_esmtpParams)
throws IOException
in_forwardAddress parameter contains the recipient's address. If your server supports Extended SMTP, you can pass ESMTP elements in the in_esmtpParams parameter. If an input or output error occurs, the method throws an IOException.
SMTPClient.rcpTo sends the RCPT TO SMTP protocol command.
NOTE: For this method's callback mapping, see SMTP Callback Mapping. §The following section of code sets the recipient.
/* After Setting the Mailer */
l_client.rcptTo( "recipient@netscape.com", null );
l_client.processResponses();After you set the recipient, the next step is Sending the Message. [Top]
SMTPClient.data, followed by the SMTPClient.send method. First, use this method:
public synchronized void data()The server responds with a success or failure reply code. See SMTP Response Codes. The
throws IOException
SMTPClient.send method delivers data to the server. If you use this method, you must send data with the SMTPClient.data method and not with SMTPClient.bdat. The SMTPClient.bdat method, which can deliver binary data, is not supported on the Netscape Messaging Server and some other servers.
After the data method, call SMTPClient.send, which sends a message to the server:
public synchronized void send(The input stream contains the data to send. When the server responds that it is ready, the client sends the RFC 822 message data line by line. You can set data chunk size with
InputStream in_inputStream) throws IOException
SMTPClient.setChunkSize, or you can use the default (1 K). You can set this at any point before the SMTPClient.send method.
NOTE: For the callback mapping for these methods, see SMTP Callback Mapping. §The following section of code uses
SMPTClient.data and SMPTClient.send to send a message.
l_client.data();
l_client.processResponses();
l_client.send( new ByteArrayInputStream( "Hello World!!!" ) );
l_client.processResponses();After you send the message and perform any other SMTP operations you need for the session, the next step is Ending the Session. To use a more convenient, but less flexible, way to send messages, see Sending Messages with Convenience APIs. [Top]
ImTransport.sendMessage and ImTransport.sendDocuments methods are for developers who want to mail-enable applications, such as spreadsheets and word processors, whose primary purpose is not messaging. Adding this mail functionality can allow the end user to mail documents or post them to a news group from within the application.
The ImTransport.sendMessage method is a convenience for sending messages. It lets the client use SMTP to send a message that is already in MIME format.
This method connects to the SMTP transport at the specified host, and submits a message created with the Netscape MIME API or in any other way. Use this syntax:
public String[] sendMessage(String host,You provide the names of the host and sender, and the email addresses of the recipients. The input stream contains the MIME message itself. The Messaging Access SDK also provides an API for building and sending a message in a single step. For more information, see Sending Documents with the Convenience API. [Top]
String sender,
String recipients[],
InputStream MIMEMessageStream)
throws IMException
SMTPClient.quit to notify the server. The server closes the TCP connection and returns a response code. You should always end a session with quit instead of just closing the connection. This method sends the QUIT SMTP protocol command:
public synchronized void quit() throws IOException
NOTE: For this method's callback mapping, see SMTP Callback Mapping. §The following section of code notifies the server that the client is terminating the session.
l_client.quit();
l_client.processResponses();[Top]
Last Updated: June 3, 1998