# Package javax.mail.internet

package javax.mail.internet

Classes specific to Internet mail systems. This package supports features that are specific to Internet mail systems based on the MIME standard (RFC 2045, RFC 2046, and RFC 2047). The IMAP, SMTP, and POP3 protocols use `MimeMessages`.

Properties

The Jakarta Mail API supports the following standard properties, which may be set in the `Session` object, or in the `Properties` object used to create the `Session` object. The properties are always set as strings; the Type column describes how the string is interpreted. For example, use

            session.setProperty("mail.mime.address.strict", "false");

to set the `mail.mime.address.strict` property, which is of type boolean.

Jakarta Mail properties
Name | Type | Description
--- | --- | ---
mail.mime.address.strict | boolean | The `mail.mime.address.strict` session property controls the parsing of address headers. By default, strict parsing of address headers is done. If this property is set to `"false"`, strict parsing is not done and many illegal addresses that sometimes occur in real messages are allowed. See the `InternetAddress` class for details.
mail.mime.allowutf8 | boolean | If set to `"true"`, UTF-8 strings are allowed in message headers, e.g., in addresses. This should only be set if the mail server also supports UTF-8.

The Jakarta Mail API specification requires support for the following properties, which must be set in the `System` properties. The properties are always set as strings; the Type column describes how the string is interpreted. For example, use

            System.setProperty("mail.mime.decodetext.strict", "false");

to set the `mail.mime.decodetext.strict` property, which is of type boolean.

Jakarta Mail System properties
Name | Type | Description
--- | --- | ---

mail.mime.charset

String

The `mail.mime.charset` System property can be used to specify the default MIME charset to use for encoded words and text parts that don't otherwise specify a charset. Normally, the default MIME charset is derived from the default Java charset, as specified in the `file.encoding` System property. Most applications will have no need to explicitly set the default MIME charset. In cases where the default MIME charset to be used for mail messages is different than the charset used for files stored on the system, this property should be set.

mail.mime.decodetext.strict

boolean

The `mail.mime.decodetext.strict` property controls decoding of MIME encoded words. The MIME spec requires that encoded words start at the beginning of a whitespace separated word. Some mailers incorrectly include encoded words in the middle of a word. If the `mail.mime.decodetext.strict` System property is set to `"false"`, an attempt will be made to decode these illegal encoded words. The default is true.

mail.mime.encodeeol.strict

boolean

The `mail.mime.encodeeol.strict` property controls the choice of Content-Transfer-Encoding for MIME parts that are not of type "text". Often such parts will contain textual data for which an encoding that allows normal end of line conventions is appropriate. In rare cases, such a part will appear to contain entirely textual data, but will require an encoding that preserves CR and LF characters without change. If the `mail.mime.encodeeol.strict` System property is set to `"true"`, such an encoding will be used when necessary. The default is false.

mail.mime.decodefilename | boolean | If set to `"true"`, the `getFileName` method uses the `MimeUtility` method `decodeText` to decode any non-ASCII characters in the filename. Note that this decoding violates the MIME specification, but is useful for interoperating with some mail clients that use this convention. The default is false.
mail.mime.encodefilename | boolean | If set to `"true"`, the `setFileName` method uses the `MimeUtility` method `encodeText` to encode any non-ASCII characters in the filename. Note that this encoding violates the MIME specification, but is useful for interoperating with some mail clients that use this convention. The default is false.
mail.mime.decodeparameters | boolean | If set to `"false"`, non-ASCII parameters in a `ParameterList`, e.g., in a Content-Type header, will not be decoded as specified by RFC 2231. The default is true.
mail.mime.encodeparameters | boolean | If set to `"false"`, non-ASCII parameters in a `ParameterList`, e.g., in a Content-Type header, will not be encoded as specified by RFC 2231. The default is true.

mail.mime.multipart. ignoremissingendboundary

boolean

Normally, when parsing a multipart MIME message, a message that is missing the final end boundary line is not considered an error. The data simply ends at the end of the input. Note that messages of this form violate the MIME specification. If the property `mail.mime.multipart.ignoremissingendboundary` is set to `false`, such messages are considered an error and a `MesagingException` will be thrown when parsing such a message.

mail.mime.multipart. ignoremissingboundaryparameter

boolean

If the Content-Type header for a multipart content does not have a `boundary` parameter, the multipart parsing code will look for the first line in the content that looks like a boundary line and extract the boundary parameter from the line. If this property is set to `"false"`, a `MessagingException` will be thrown if the Content-Type header doesn't specify a boundary parameter. The default is true.

mail.mime.multipart. ignoreexistingboundaryparameter

boolean

Normally the boundary parameter in the Content-Type header of a multipart body part is used to specify the separator between parts of the multipart body. This System property may be set to `"true"` to cause the parser to look for a line in the multipart body that looks like a boundary line and use that value as the separator between subsequent parts. This may be useful in cases where a broken anti-virus product has rewritten the message incorrectly such that the boundary parameter and the actual boundary value no longer match. The default value of this property is false.

mail.mime.multipart. allowempty

boolean

Normally, when writing out a MimeMultipart that contains no body parts, or when trying to parse a multipart message with no body parts, a `MessagingException` is thrown. The MIME spec does not allow multipart content with no body parts. This System property may be set to `"true"` to override this behavior. When writing out such a MimeMultipart, a single empty part will be included. When reading such a multipart, a MimeMultipart will be created with no body parts. The default value of this property is false.

The following properties are supported by the EE4J implementation of Jakarta Mail, but are not currently a required part of the specification. These must be set as `Session` properties. The names, types, defaults, and semantics of these properties may change in future releases.

Jakarta Mail implementation properties
Name | Type | Description
--- | --- | ---
mail.alternates | String | A string containing other email addresses that the current user is known by. The `MimeMessage` `reply` method will eliminate any of these addresses from the recipient list in the message it constructs, to avoid sending the reply back to the sender.
mail.replyallcc | boolean | If set to `"true"`, the `MimeMessage` `reply` method will put all recipients except the original sender in the `Cc` list of the newly constructed message. Normally, recipients in the `To` header of the original message will also appear in the `To` list of the newly constructed message.

The following properties are supported by the EE4J implementation of Jakarta Mail, but are not currently a required part of the specification. These must be set as `System` properties. The names, types, defaults, and semantics of these properties may change in future releases.

Jakarta Mail implementation System properties
Name | Type | Description
--- | --- | ---

mail.mime.base64.ignoreerrors

boolean

If set to `"true"`, the BASE64 decoder will ignore errors in the encoded data, returning EOF. This may be useful when dealing with improperly encoded messages that contain extraneous data at the end of the encoded stream. Note however that errors anywhere in the stream will cause the decoder to stop decoding so this should be used with extreme caution. The default is false.

mail.mime.foldtext | boolean | If set to `"true"`, header fields containing just text such as the `Subject` and `Content-Description` header fields, and long parameter values in structured headers such as `Content-Type` will be folded (broken into 76 character lines) when set and unfolded when read. The default is true.
mail.mime.setcontenttypefilename | boolean | If set to `"true"`, the `setFileName` method will also set the `name` parameter on the `Content-Type` header to the specified filename. This supports interoperability with some old mail clients. The default is true.
mail.mime.setdefaulttextcharset | boolean | When updating the headers of a message, a body part with a `text` content type but no `charset` parameter will have a `charset` parameter added to it if this property is set to `"true"`. The default is true.

mail.mime.parameters.strict

boolean

If set to false, when reading a message, parameter values in header fields such as `Content-Type` and `Content-Disposition` are allowed to contain whitespace and other special characters without being quoted; the parameter value ends at the next semicolon. If set to true (the default), parameter values are required to conform to the MIME specification and must be quoted if they contain whitespace or special characters.

mail.mime.applefilenames

boolean

Apple Mail incorrectly encodes filenames that contain spaces, forgetting to quote the parameter value. If this property is set to `"true"`, Jakarta Mail will try to detect this situation when parsing parameters and work around it. The default is false. Note that this property handles a subset of the cases handled by setting the mail.mime.parameters.strict property to false. This property will likely be removed in a future release.

mail.mime.windowsfilenames

boolean

Internet Explorer 6 incorrectly includes a complete pathname in the filename parameter of the Content-Disposition header for uploaded files, and fails to properly escape the backslashes in the pathname. If this property is set to `"true"`, Jakarta Mail will preserve all backslashes in the "filename" and "name" parameters of any MIME header. The default is false. Note that this is a violation of the MIME specification but may be useful when using Jakarta Mail to parse HTTP messages for uploaded files sent by IE6.

mail.mime. ignoreunknownencoding | boolean | If set to `"true"`, an unknown value in the `Content-Transfer-Encoding` header will be ignored when reading a message and an encoding of "8bit" will be assumed. If set to `"false"`, an exception is thrown for an unknown encoding value. The default is false.
mail.mime.uudecode. ignoreerrors | boolean | If set to `"true"`, errors in the encoded format of a uuencoded document will be ignored when reading a message part. If set to `"false"`, an exception is thrown for an incorrectly encoded message part. The default is false.
mail.mime.uudecode. ignoremissingbeginend | boolean | If set to `"true"`, a missing "being" or "end" line in a uuencoded document will be ignored when reading a message part. If set to `"false"`, an exception is thrown for a uuencoded message part without the required "begin" and "end" lines. The default is false.
mail.mime. ignorewhitespacelines | boolean | Normally the header of a MIME part is separated from the body by an empty line. This System property may be set to `"true"` to cause the parser to consider a line containing only whitespace to be an empty line. The default value of this property is false.
mail.mime. ignoremultipartencoding | boolean | The MIME spec does not allow body parts of type multipart/* to be encoded. The Content-Transfer-Encoding header is ignored in this case. Setting this System property to `"false"` will cause the Content-Transfer-Encoding header to be honored for multipart content. The default value of this property is true.

mail.mime.allowencodedmessages

boolean

The MIME spec does not allow body parts of type message/* to be encoded. The Content-Transfer-Encoding header is ignored in this case. Some versions of Microsoft Outlook will incorrectly encode message attachments. Setting this System property to `"true"` will cause the Content-Transfer-Encoding header to be honored for message attachments. The default value of this property is false.

mail.mime.contenttypehandler

String

In some cases Jakarta Mail is unable to process messages with an invalid Content-Type header. The header may have incorrect syntax or other problems. This property specifies the name of a class that will be used to clean up the Content-Type header value before Jakarta Mail uses it. The class must have a method with this signature: `public static String cleanContentType(MimePart mp, String contentType)` Whenever Jakarta Mail accesses the Content-Type header of a message, it will pass the value to this method and use the returned value instead. The value may be null if the Content-Type header isn't present. Returning null will cause the default Content-Type to be used. The MimePart may be used to access other headers of the message part to determine how to correct the Content-Type. Note that the Content-Type handler doesn't affect the `getHeader` method, which still returns the raw header value. Note also that the handler doesn't affect the IMAP provider; the IMAP server is responsible for returning pre-parsed, syntactically correct Content-Type information.

mail.mime.address.usecanonicalhostname

boolean

Use the `InetAddress.getCanonicalHostName` method to determine the host name in the `InternetAddress.getLocalAddress` method. With some network configurations, InetAddress.getCanonicalHostName may be slow or may return an address instead of a host name. In that case, setting this System property to false will cause the `InetAddress.getHostName` method to be used instead. The default is true.

The current implementation of classes in this package log debugging information using `Logger` as described in the following table:

Jakarta Mail Loggers
Logger Name | Logging Level | Purpose
--- | --- | ---
javax.mail.internet | FINE | General debugging output

Related Packages
Package
Description
javax.mail
The Jakarta Mail API provides classes that model a mail system.
javax.mail.event
Listeners and events for the Jakarta Mail API.
javax.mail.search
Message search terms for the Jakarta Mail API.
javax.mail.util
Jakarta Mail API utility classes.
Class
Description
AddressException
The exception thrown when a wrongly formatted address is encountered.
AsciiOutputStream
An OutputStream that determines whether the data written to it is all ASCII, mostly ASCII, or mostly non-ASCII.
ContentDisposition
This class represents a MIME ContentDisposition value.
ContentType
This class represents a MIME Content-Type value.
HeaderTokenizer
This class tokenizes RFC822 and MIME headers into the basic symbols specified by RFC822 and MIME.
HeaderTokenizer.Token
The Token class represents tokens returned by the HeaderTokenizer.
InternetAddress
This class represents an Internet email address using the syntax of RFC822.
InternetHeaders
InternetHeaders is a utility class that manages RFC822 style headers.
InternetHeaders.InternetHeader
An individual internet header.
MailDateFormat
Formats and parses date specification based on RFC 2822.
MimeBodyPart
This class represents a MIME body part.
MimeMessage
This class represents a MIME style email message.
MimeMessage.RecipientType
This inner class extends the javax.mail.Message.RecipientType class to add additional RecipientTypes.
MimeMultipart
The MimeMultipart class is an implementation of the abstract Multipart class that uses MIME conventions for the multipart data.
MimePart
The MimePart interface models an Entity as defined by MIME (RFC2045, Section 2.4).
MimePart
The MimePart interface models an Entity as defined by MIME (RFC2045, Section 2.4).
MimePartDataSource
A utility class that implements a DataSource out of a MimePart.
MimeUtility
This is a utility class that provides various MIME related functionality.
NewsAddress
This class models an RFC1036 newsgroup address.
ParameterList
This class holds MIME parameters (attribute-value pairs).
ParseException
The exception thrown due to an error in parsing RFC822 or MIME headers, including multipart bodies.
PreencodedMimeBodyPart
A MimeBodyPart that handles data that has already been encoded.
SharedInputStream
An InputStream that is backed by data that can be shared by multiple readers may implement this interface.
SharedInputStream
An InputStream that is backed by data that can be shared by multiple readers may implement this interface.
UniqueValue
This is a utility class that generates unique values.