Package com.sun.mail.smtp

See:
          Description

Package com.sun.mail.smtp Description

When sending a message, detailed information on each address that fails is available in an {@link com.sun.mail.smtp.SMTPAddressFailedException SMTPAddressFailedException} chained off the top level {@link javax.mail.SendFailedException SendFailedException} that is thrown. In addition, if the mail.smtp.reportsuccess property is set, an {@link com.sun.mail.smtp.SMTPAddressSucceededException SMTPAddressSucceededException} will be included in the list for each address that is successful. Note that this will cause a top level {@link javax.mail.SendFailedException SendFailedException} to be thrown even though the send was successful.

The SMTP provider also supports ESMTP (RFC 1651). It can optionally use SMTP Authentication (RFC 2554) using the LOGIN, PLAIN, and DIGEST-MD5 mechanisms (RFC 2592 and RFC 2831).

To use SMTP authentication you'll need to set the mail.smtp.auth property (see below) and provide the SMTP Transport with a username and password when connecting to the SMTP server. You can do this using one of the following approaches:

• Provide an Authenticator object when creating your mail Session and provide the username and password information during the Authenticator callback.

  Note that the mail.smtp.user property can be set to provide a default username for the callback, but the password will still need to be supplied explicitly.

  This approach allows you to use the static Transport send method to send messages.

• Call the Transport connect method explicitly with username and password arguments.

  This approach requires you to explicitly manage a Transport object and use the Transport sendMessage method to send the message. The transport.java demo program demonstrates how to manage a Transport object. The following is roughly equivalent to the static Transport send method, but supplies the needed username and password:

  Transport tr = session.getTransport("smtp");
  tr.connect(smtphost, username, password);
  msg.saveChanges();	// don't forget this
  tr.sendMessage(msg, msg.getAllRecipients());
  tr.close();
  

When using DIGEST-MD5 authentication, you'll also need to supply an appropriate realm; your mail server administrator can supply this information. You can set this using the mail.smtp.sasl.realm property, or the setSASLRealm method on SMTPTransport.

SMTP can also optionally request Delivery Status Notifications (RFC 1891). The delivery status will typically be reported using a "multipart/report" (RFC 1892) message type with a "message/delivery-status" (RFC 1894) part. JavaMail does not currently provide direct support for these new MIME types, but you can process them as any other "multipart" or "message" content, using MimeMultipart and MimeMessage objects.

See below for the properties to enable these features.

Note also that THERE IS NOT SUFFICIENT DOCUMENTATION HERE TO USE THESE FEATURES!!! You will need to read the appropriate RFCs mentioned above to understand what these features do and how to use them. Don't just start setting properties and then complain to us when it doesn't work like you expect it to work. READ THE RFCs FIRST!!!

The SMTP protocol provider supports the following properties, which may be set in the JavaMail Session object. The properties are always set as strings; the Type column describes how the string is interpreted. For example, use

	props.put("mail.smtp.port", "888");

In general, applications should not need to use the classes in this package directly. Instead, they should use the APIs defined by javax.mail package (and subpackages). Applications should never construct instances of SMTPTransport directly. Instead, they should use the Session method getTransport to acquire an appropriate Transport object.

WARNING: The APIs unique to this package should be considered EXPERIMENTAL. They may be changed in the future in ways that are incompatible with applications using the current APIs.