com.upokecenter.mail.Message

com.upokecenter.mail.Message

public final class Message extends Object

Represents an email message, and contains methods and properties for accessing and modifying email message data. This class implements the Internet Message Format (RFC 5322) and Multipurpose Internet Mail Extensions (MIME; RFC 2045-2047, RFC 2049).

Thread safety: This class is mutable; its properties can be changed. None of its instance methods are designed to be thread safe. Therefore, access to objects from this class must be synchronized if multiple threads can access them at the same time.

The following lists known deviations from the mail specifications (Internet Message Format and MIME):

• If a message has two or more Content-Type header fields, it is treated as having a content type of "application/octet-stream", unless one or more of the header fields is syntactically invalid.
• Illegal UTF-8 byte sequences appearing in header field values are replaced with replacement characters. Moreover, UTF-8 is parsed everywhere in header field values, even in those parts of some structured header fields where this appears not to be allowed. (UTF-8 is a character encoding for the Unicode character set.)
• This implementation can parse a message even if that message is without a From header field, without a Date header field, or without both.
• The To and Cc header fields are allowed to contain only comments and whitespace, but these "empty" header fields will be omitted when generating.
• There is no line length limit imposed when parsing header fields, except header field names.
• There is no line length limit imposed when parsing quoted-printable or base64 encoded bodies.
• If the transfer encoding is absent and the content type is "message/rfc822", bytes with values greater than 127 are still allowed, despite the default value of "7bit" for "Content-Transfer-Encoding".
• In the following cases, if the transfer encoding is absent, declared as 7bit, or treated as 7bit, bytes greater than 127 are still allowed:
• (a) The preamble and epilogue of multipart messages, which will be ignored.
• (b) If the charset is declared to be utf-8.
• (c) If the content type is "text/html" and the charset is declared to be us-ascii, "windows-1252", "windows-1251", or "iso-8859-*" (all single byte encodings).
• (d) In text/plain message bodies. Any bytes greater than 127 are replaced with the substitute character byte (0x1a).
• (e) In MIME message bodies (this is not a deviation from MIME, though). Any bytes greater than 127 are replaced with the substitute character byte (0x1a).
• If the message starts with the word "From" (and no other case variations of that word) followed by one or more space (U+0020) not followed by colon, that text and the rest of the text is skipped up to and including a line feed (U+000A). (See also RFC 4155, which describes the so-called "mbox" convention with "From" lines of this kind.)
• The name ascii is treated as a synonym for us-ascii, despite being a reserved name under RFC 2046. The names cp1252 and utf8 are treated as synonyms for windows-1252 and utf-8, respectively, even though they are not IANA registered aliases.
• The following deviations involve encoded words under RFC 2047:
• (a) If a sequence of encoded words decodes to a string with a CTL character (U+007F, or a character less than U+0020 and not TAB) after being converted to Unicode, the encoded words are left un-decoded.
• (b) This implementation can decode encoded words regardless of the character length of the line in which they appear. This implementation can generate a header field line with one or more encoded words even if that line is more than 76 characters long. (This implementation follows the recommendation in RFC 5322 to limit header field lines to no more than 78 characters, where possible; see also RFC 6532.)

It would be appreciated if users of this library contact the author if they find other ways in which this implementation deviates from the mail specifications or other applicable specifications.

If a MIME message or body part has an unrecognized transfer encoding, its content type is treated as "application/octet-stream" rather than the declared content type (in accordance with MIME) and its transfer encoding is treated as 7bit (a clarification to MIME).

This class currently doesn't support the "padding" parameter for message bodies with the media type "application/octet-stream" or treated as that media type (see RFC 2046 sec. 4.5.1).

In this implementation, if the content-transfer-encoding "quoted-printable" or "base64" occurs in a message or body part with content type "multipart/*" or "message/*" (other than "message/global", "message/global-headers", "message/global-disposition-notification", or "message/global-delivery-status"), that encoding is treated as unrecognized for the purpose of treating that message or body part as having a content type of "application/octet-stream" rather than the declared content type. This is a clarification to RFCs 2045 and 2049. (This may result in "misdecoded" messages because in practice, most if not all messages of this kind don't use quoted-printable or base64 encodings for the whole body, but may do so in the body parts they contain.)

This implementation can decode an RFC 2047 encoded word that uses ISO-2022-JP or ISO-2022-JP-2 (encodings that use code switching) even if the encoded word's payload ends in a different mode from "ASCII mode". (Each encoded word still starts in "ASCII mode", though.) This, however, is not a deviation to RFC 2047 because the relevant rule only concerns bringing the output device back to "ASCII mode" after the decoded text is displayed (see last paragraph of sec. 6.2) -- since the decoded text is converted to Unicode rather than kept as ISO-2022-JP or ISO-2022-JP-2, this is not applicable since there is no such thing as "ASCII mode" in the Unicode Standard.

Note that this library (the MailLib library) has no facilities for sending and receiving email messages, since that's outside this library's scope.

Constructors

Methods

• Message AddAttachment(MediaType mediaType)
  Adds an attachment with an empty body and with the given media type to this message.

• Message AddAttachment(InputStream inputStream, MediaType mediaType)
  Adds an attachment to this message in the form of data from the given readable stream, and with the given media type.

• Message AddAttachment(InputStream inputStream, MediaType mediaType, String filename)
  Adds an attachment to this message in the form of data from the given readable stream, and with the given media type and file name.

• Message AddAttachment(InputStream inputStream, String filename)
  Adds an attachment to this message in the form of data from the given readable stream, and with the given file name.

• Message AddHeader(String name, String value)
  Adds a header field to the end of the message's header.

• Message AddHeader(Map.Entry<String,String> header)
  Adds a header field to the end of the message's header.

• Message AddInline(MediaType mediaType)
  Adds an inline body part with an empty body and with the given media type to this message.

• Message AddInline(InputStream inputStream, MediaType mediaType)
  Adds an inline body part to this message in the form of data from the given readable stream, and with the given media type.

• Message AddInline(InputStream inputStream, MediaType mediaType, String filename)
  Adds an inline body part to this message in the form of data from the given readable stream, and with the given media type and file name.

• Message AddInline(InputStream inputStream, String filename)
  Adds an inline body part to this message in the form of data from the given readable stream, and with the given file name.

• Message ClearHeaders()
  Deletes all header fields in this message.

• static String DecodeHeaderValue(String name, String value)
  Decodes RFC 2047 encoded words from the given header field value and returns a string with those words decoded.

• static String ExtractHeader(byte[] bytes, String headerFieldName)
  Extracts the value of a header field from a byte array representing an email message.

• static Message FromMailtoUri(String uri)
  Creates a message object from a MailTo URI (uniform resource identifier).

• static Message FromMailtoUri(URI uri)
  Creates a message object from a MailTo URI (uniform resource identifier) in the form of a URI object.

• static Message FromMailtoUrl(String url)
  Deprecated. Renamed to FromMailtoUri.

• String Generate()
  Generates this message's data in text form.

• byte[] GenerateBytes()
  Generates this message's data as a byte array, using the same algorithm as the Generate method.

• List<NamedAddress> GetAddresses(String headerName)
  Gets a list of addresses contained in the header fields with the given name in this message.

• List<Message> GetAttachments()
  Gets a list of descendant body parts of this message that are considered attachments.

• final List<NamedAddress> getBccAddresses()
  Deprecated. Use GetAddresses(\Bcc) instead.

• byte[] GetBody()
  Gets the byte array for this message's body.

• Message GetBodyMessage()
  Returns the mail message contained in this message's body.

• final String getBodyString()
  Deprecated. Use GetBodyString() instead.

• String GetBodyString()
  Gets the body of this message as a text string.

• final List<NamedAddress> getCCAddresses()
  Deprecated. Use GetAddresses(\Cc) instead.

• final ContentDisposition getContentDisposition()
  Gets this message's content disposition.

• final MediaType getContentType()
  Gets this message's media type.

• int[] GetDate()
  Gets the date and time extracted from this message's Date header field (the value of which is found as though GetHeader("date") were called).

• final String getFileName()
  Gets a file name suggested by this message for saving the message's body to a file.

• String GetFormattedBodyString()
  Gets a Hypertext Markup Language (HTML) rendering of this message's text body.

• final List<NamedAddress> getFromAddresses()
  Deprecated. Use GetAddresses(\From) instead.

• Map.Entry<String,String> GetHeader(int index)
  Gets the name and value of a header field by index.

• String GetHeader(String name)
  Gets the first instance of the header field with the specified name, using a basic case-insensitive comparison.

• String[] GetHeaderArray(String name)
  Gets an array with the values of all header fields with the specified name, using a basic case-insensitive comparison.

• final List<Map.Entry<String,String>> getHeaderFields()
  Gets a snapshot of the header fields of this message, in the order in which they appear in the message.

• final List<Message> getParts()
  Gets a list of all the parts of this message.

• final String getSubject()
  Gets this message's subject.

• final List<NamedAddress> getToAddresses()
  Deprecated. Use GetAddresses(\To) instead.

• static Message MakeMultilingualMessage(List<Message> messages, List<String> languages)
  Generates a multilingual message (see RFC 8255) from a list of messages and a list of language strings.

• static Message NewBodyPart()
  Creates a message object with no header fields.

• Message RemoveHeader(int index)
  Removes a header field by index.

• Message RemoveHeader(String name)
  Removes all instances of the given header field from this message.

• Message SelectLanguageMessage(List<String> languages)
  Selects a body part for a multiple-language message( multipart/multilingual) according to the given language priority list.

• Message SelectLanguageMessage(List<String> languages, boolean preferOriginals)
  Selects a body part for a multiple-language message( multipart/multilingual) according to the given language priority list and original-language preference.

• Message SetBody(byte[] bytes)
  Sets the body of this message to the given byte array.

• final void setContentDisposition(ContentDisposition value)
   

• final void setContentType(MediaType value)
   

• Message SetCurrentDate()
  Sets this message's Date header field to the current time as its value, with an unspecified time zone offset.

• Message SetDate(int[] dateTime)
  Sets this message's Date header field to the given date and time.

• Message SetHeader(int index, String value)
  Sets the value of a header field by index without changing its name.

• Message SetHeader(int index, String name, String value)
  Sets the name and value of a header field by index.

• Message SetHeader(int index, Map.Entry<String,String> header)
  Sets the name and value of a header field by index.

• Message SetHeader(String name, String value)
  Sets the value of this message's header field.

• Message SetHtmlBody(String str)
  Sets the body of this message to the specified string in Hypertext Markup Language (HTML) format.

• final void setSubject(String value)
   

• Message SetTextAndHtml(String text, String html)
  Sets the body of this message to a multipart body with plain text and Hypertext Markup Language (HTML) versions of the same message.

• Message SetTextAndMarkdown(String text, String markdown)
  Sets the body of this message to a multipart body with plain text, Markdown, and Hypertext Markup Language (HTML) versions of the same message.

• Message SetTextBody(String str)
  Sets the body of this message to the specified plain text string.

• String ToMailtoUri()
  Generates a MailTo URI (uniform resource identifier) corresponding to this message.

• String ToMailtoUrl()
  Deprecated. Renamed to ToMailtoUri.

Method Details

ExtractHeader

public static String ExtractHeader(byte[] bytes, String headerFieldName)

Extracts the value of a header field from a byte array representing an email message. The return value is intended for display purposes, not for further processing, and this method is intended to be used as an error handling tool for email messages that are slightly malformed. (Note that malformed email messages ought to be treated with greater suspicion than well-formed email messages.).

Parameters:

• bytes - A byte array representing an email message.

• headerFieldName - The name of the header field to extract. This name will be compared with the names of header fields in the given message using a basic case-insensitive comparison. (Two strings are equal in such a comparison, if they match after converting the basic upper-case letters A to Z (U+0041 to U+005A) in both strings to basic lower-case letters.).

Returns:

• The value of the first instance of the header field with the given name. Leading space and/or tab bytes (0x20 and/or 0x09) and CR/LF (0x0d/0x0a) pairs will be removed from the header field value, and the value is treated as encoded in UTF-8 (an 8-bit encoding form of the Unicode Standard) where illegally encoded UTF-8 is replaced as appropriate with replacement characters (U+FFFD). Returns null if bytes is null, if headerFieldName is null, is more than 997 characters long, or has a character less than U+0021 or greater than U+007E in the Unicode Standard, if a header field with that name does not exist, or if a body (even an empty one) does not follow the header fields.

NewBodyPart

public static Message NewBodyPart()

Creates a message object with no header fields.

Returns:

• A message object with no header fields.

SetCurrentDate

public Message SetCurrentDate()

Sets this message's Date header field to the current time as its value, with an unspecified time zone offset.

This method can be used when the message is considered complete and ready to be generated, for example, using the "Generate()" method.

Returns:

• This object.

getBccAddresses

@Deprecated public final List<NamedAddress> getBccAddresses()

Gets a list of addresses found in the BCC header field or fields.

Returns:

• A list of addresses found in the BCC header field or fields.

getBodyString

@Deprecated public final String getBodyString()

Gets the body of this message as a text string. See the GetBodyString() method.

Returns:

• The body of this message as a text string.

Throws:

• UnsupportedOperationException - See the GetBodyString() method.

GetAttachments

public List<Message> GetAttachments()

Gets a list of descendant body parts of this message that are considered attachments. An attachment is a body part or descendant body part that has a content disposition with a type other than inline. This message itself is not included in the list even if it's an attachment as just defined.

Returns:

• A list of descendant body parts of this message that are considered attachments.

GetBodyString

public String GetBodyString()

Gets the body of this message as a text string. If this message's media type is "multipart/alternative", returns the result of this method for the last supported body part. For any other "multipart" media type, returns the result of this method for the first body part for which this method returns a text string.

Returns:

• The body of this message as a text string.

Throws:

• UnsupportedOperationException - This message is a multipart message without a supported body part; or this message has a content disposition with a type other than "inline"; or this message's media type is a non-multipart type and does not specify the use of a "charset" parameter, has no character encoding declared or assumed for it (which is usually the case for non-text messages), or has an unsupported character encoding.

getCCAddresses

@Deprecated public final List<NamedAddress> getCCAddresses()

Gets a list of addresses found in the CC header field or fields.

Returns:

• A list of addresses found in the CC header field or fields.

GetFormattedBodyString

public String GetFormattedBodyString()

Gets a Hypertext Markup Language (HTML) rendering of this message's text body. This method currently supports any message for which GetBodyString() outputs a text string and treats the following media types specially: text/plain with format = flowed, text/enriched, text/markdown (original Markdown).

REMARK: The Markdown implementation currently supports all features of original Markdown, except that the implementation:

• does not strictly check the placement of "block-level HTML elements",
• does not prevent Markdown content from being interpreted as such merely because it's contained in a "block-level HTML element", and
• does not deliberately use HTML escapes to obfuscate email addresses wrapped in angle-brackets.

Gets a file name suggested by this message for saving the message's body to a file. For more information on the algorithm, see ContentDisposition.MakeFilename.

This method generates a file name based on the filename parameter of the Content-Disposition header field, if it exists, or on the name parameter of the Content-Type header field, otherwise.

Returns:

• A suggested name for the file. Returns the empty string if there is no filename suggested by the content type or content disposition, or if that filename is an empty string.

GetAddresses

public List<NamedAddress> GetAddresses(String headerName)

Gets a list of addresses contained in the header fields with the given name in this message.

Parameters:

• headerName - The name of the header fields to retrieve.

Returns:

• A list of addresses, in the order in which they appear in this message's header fields of the given name.

Throws:

• UnsupportedOperationException - The parameter headerName is not supported for this method. Currently, the only header fields supported are To, Cc, Bcc, Reply-To, Sender, and From.

• NullPointerException - The parameter headerName is null.

• IllegalArgumentException - The parameter headerName is empty.

getFromAddresses

@Deprecated public final List<NamedAddress> getFromAddresses()

Gets a list of addresses found in the From header field or fields.

Returns:

• A list of addresses found in the From header field or fields.

getHeaderFields

public final List<Map.Entry<String,String>> getHeaderFields()

Gets a snapshot of the header fields of this message, in the order in which they appear in the message. For each item in the list, the key is the header field's name (where any basic upper-case letters, U+0041 to U+005A, are converted to basic lower-case letters) and the value is the header field's value.

Returns:

• A snapshot of the header fields of this message.

getParts

public final List<Message> getParts()

Gets a list of all the parts of this message. This list is editable. This will only be used if the message is a multipart message.

Returns:

• A list of all the parts of this message. This list is editable. This will only be used if the message is a multipart message.

getSubject

public final String getSubject()

Gets this message's subject. The subject's value is found as though GetHeader("subject") were called.

Returns:

• This message's subject, or null if there is none.

setSubject

public final void setSubject(String value)

getToAddresses

@Deprecated public final List<NamedAddress> getToAddresses()

Gets a list of addresses found in the To header field or fields.

Returns:

• A list of addresses found in the To header field or fields.

AddHeader

public Message AddHeader(Map.Entry<String,String> header)

Adds a header field to the end of the message's header.

This method updates the ContentType and ContentDisposition properties if those header fields have been modified by this method.

Parameters:

• header - A key/value pair. The key is the name of the header field, such as "From" or "Content-ID". The value is the header field's value.

Returns:

• This instance.

Throws:

• NullPointerException - The key or value of header is null.

• IllegalArgumentException - The header field name is too long or contains an invalid character, or the header field's value is syntactically invalid.

AddHeader

public Message AddHeader(String name, String value)

Adds a header field to the end of the message's header.

This method updates the ContentType and ContentDisposition properties if those header fields have been modified by this method.

Parameters:

• name - Name of a header field, such as "From" or "Content-ID" .

• value - Value of the header field.

Returns:

• This instance.

Throws:

• NullPointerException - The parameter name or value is null.

• IllegalArgumentException - The header field name is too long or contains an invalid character, or the header field's value is syntactically invalid.

Generate

public String Generate()

Generates this message's data in text form.

The generated message will have only Basic Latin code points (U+0000 to U+007F), and the transfer encoding will always be 7bit, quoted-printable, or base64 (the declared transfer encoding for this message will be ignored).

The following applies to the following header fields: From, To, Cc, Bcc, Reply-To, Sender, Resent-To, Resent-From, Resent-Cc, Resent-Bcc, and Resent-Sender. If the header field exists, but has an invalid syntax, has no addresses, or appears more than once, this method will combine the addresses into one header field if possible (in the case of all fields given other than From and Sender), and otherwise generate a synthetic header field with the display-name set to the contents of all of the header fields with the same name, and the address set to me@[header-name]-address.invalid as the address (a .invalid address is a reserved address that can never belong to anyone). (An exception is that the Resent-* header fields may appear more than once.) The generated message should always have a From header field.

If a Date and/or Message-ID header field doesn't exist, a field with that name will be generated (using the current local time for the Date field).

When encoding the message's body, if the message has a text content type ("text/*"), the line breaks are a CR byte (carriage return, 0x0d) followed by an LF byte (line feed, 0x0a), CR alone, or LF alone. If the message has any other content type, only CR followed by LF is considered a line break.

Returns:

• The generated message.

Throws:

• MessageDataException - The message can't be generated.

GenerateBytes

public byte[] GenerateBytes()

Generates this message's data as a byte array, using the same algorithm as the Generate method.

Returns:

• The generated message as a byte array.

GetBody

public byte[] GetBody()

Gets the byte array for this message's body. This method doesn' t make a copy of that byte array.

Returns:

• A byte array.

GetDate

public int[] GetDate()

Gets the date and time extracted from this message's Date header field (the value of which is found as though GetHeader("date") were called). See MailDateTime.ParseDateString(string, boolean) for more information on the format of the date-time array returned by this method.

Returns:

• An array of 32-bit unsigned integers.

SetDate

public Message SetDate(int[] dateTime)

Sets this message's Date header field to the given date and time.

Parameters:

• dateTime -

  An array containing at least eight elements expressing a date and time. See MailDateTime.ParseDateString(string, boolean) for more information on this parameter.

Returns:

• This object.

Throws:

• IllegalArgumentException - The parameter dateTime contains fewer than eight elements or contains invalid values (see MailDateTime.ParseDateString(string, boolean)).

• NullPointerException - The parameter dateTime is null.

GetBodyMessage

public Message GetBodyMessage()

Returns the mail message contained in this message's body.

Returns:

• A message object if this object's content type is "message/rfc822", "message/news", or "message/global", or null otherwise.

GetHeader

public Map.Entry<String,String> GetHeader(int index)

Gets the name and value of a header field by index.

Parameters:

• index - Zero-based index of the header field to get.

Returns:

• A key/value pair. The key is the name of the header field, such as "From" or "Content-ID". The value is the header field's value.

Throws:

• IllegalArgumentException - The parameter index is 0 or at least as high as the number of header fields.

GetHeader

public String GetHeader(String name)

Gets the first instance of the header field with the specified name, using a basic case-insensitive comparison. (Two strings are equal in such a comparison, if they match after converting the basic upper-case letters A to Z (U+0041 to U+005A) in both strings to basic lower-case letters.).

Parameters:

• name - The name of a header field.

Returns:

• The value of the first header field with that name, or null if there is none.

Throws:

• NullPointerException - Name is null.

GetHeaderArray

public String[] GetHeaderArray(String name)

Gets an array with the values of all header fields with the specified name, using a basic case-insensitive comparison. (Two strings are equal in such a comparison, if they match after converting the basic upper-case letters A to Z (U+0041 to U+005A) in both strings to basic lower-case letters.).

Parameters:

• name - The name of a header field.

Returns:

• An array containing the values of all header fields with the given name, in the order they appear in the message. The array will be empty if no header field has that name.

Throws:

• NullPointerException - Name is null.

ClearHeaders

public Message ClearHeaders()

Deletes all header fields in this message. Also clears this message's content disposition and resets its content type to MediaType.TextPlainAscii.

Returns:

• This object.

RemoveHeader

public Message RemoveHeader(int index)

Removes a header field by index.

This method updates the ContentType and ContentDisposition properties if those header fields have been modified by this method.

Parameters:

• index - Zero-based index of the header field to set.

Returns:

• This instance.

Throws:

• IllegalArgumentException - The parameter index is 0 or at least as high as the number of header fields.

RemoveHeader

public Message RemoveHeader(String name)

Removes all instances of the given header field from this message. If this is a multipart message, the header field is not removed from its body part headers. A basic case-insensitive comparison is used. (Two strings are equal in such a comparison, if they match after converting the basic upper-case letters A to Z (U+0041 to U+005A) in both strings to basic lower-case letters.).

This method updates the ContentType and ContentDisposition properties if those header fields have been modified by this method.

Parameters:

• name - The name of the header field to remove.

Returns:

• This instance.

Throws:

• NullPointerException - The parameter name is null.

SetBody

public Message SetBody(byte[] bytes)

Sets the body of this message to the given byte array. This method doesn't make a copy of that byte array.

Parameters:

• bytes - A byte array.

Returns:

• This object.

Throws:

• NullPointerException - The parameter bytes is null.

SetHeader

public Message SetHeader(int index, Map.Entry<String,String> header)

Sets the name and value of a header field by index.

This method updates the ContentType and ContentDisposition properties if those header fields have been modified by this method.

Parameters:

• index - Zero-based index of the header field to set.

• header - A key/value pair. The key is the name of the header field, such as "From" or "Content-ID". The value is the header field's value.

Returns:

• A Message object.

Throws:

• IllegalArgumentException - The parameter index is 0 or at least as high as the number of header fields; or, the header field name is too long or contains an invalid character, or the header field's value is syntactically invalid.

• NullPointerException - The key or value of header is null.

SetHeader

public Message SetHeader(int index, String name, String value)

Sets the name and value of a header field by index.

This method updates the ContentType and ContentDisposition properties if those header fields have been modified by this method.

Parameters:

• index - Zero-based index of the header field to set.

• name - Name of a header field, such as "From" or "Content-ID" .

• value - Value of the header field.

Returns:

• This instance.

Throws:

• IllegalArgumentException - The parameter index is 0 or at least as high as the number of header fields; or, the header field name is too long or contains an invalid character, or the header field's value is syntactically invalid.

• NullPointerException - The parameter name or value is null.

SetHeader

public Message SetHeader(int index, String value)

Sets the value of a header field by index without changing its name.

This method updates the ContentType and ContentDisposition properties if those header fields have been modified by this method.

Parameters:

• index - Zero-based index of the header field to set.

• value - Value of the header field.

Returns:

• This instance.

Throws:

• IllegalArgumentException - The parameter index is 0 or at least as high as the number of header fields; or, the header field name is too long or contains an invalid character, or the header field's value is syntactically invalid.

• NullPointerException - The parameter value is null.

DecodeHeaderValue

public static String DecodeHeaderValue(String name, String value)

Decodes RFC 2047 encoded words from the given header field value and returns a string with those words decoded. For an example of encoded words, see the constructor for PeterO.Mail.NamedAddress.

Parameters:

• name - Name of the header field. This determines the syntax of the "value" parameter and is necessary to help this method interpret encoded words properly.

• value - A header field value that could contain encoded words. For example, if the name parameter is "From", this parameter could be "=?utf-8?q?me?= <me@example.com>".

Returns:

• The header field value with valid encoded words decoded.

Throws:

• NullPointerException - The parameter name is null.

SetHeader

public Message SetHeader(String name, String value)

Sets the value of this message's header field. If a header field with the same name exists, its value is replaced. If the header field's name occurs more than once, only the first instance of the header field is replaced.

This method updates the ContentType and ContentDisposition properties if those header fields have been modified by this method.

Parameters:

• name - The name of a header field, such as "from" or "subject" .

• value - The header field's value.

Returns:

• This instance.

Throws:

• IllegalArgumentException - The header field name is too long or contains an invalid character, or the header field's value is syntactically invalid.

• NullPointerException - The parameter name or value is null.

SetHtmlBody

public Message SetHtmlBody(String str)

Sets the body of this message to the specified string in Hypertext Markup Language (HTML) format. The character sequences CR (carriage return, "\r", U+000D), LF (line feed, "\n", U+000A), and CR/LF will be converted to CR/LF line breaks. Unpaired surrogate code points will be replaced with replacement characters.

Parameters:

• str - A string consisting of the message in HTML format.

Returns:

• This instance.

Throws:

• NullPointerException - The parameter str is null.

SetTextAndHtml

public Message SetTextAndHtml(String text, String html)

Sets the body of this message to a multipart body with plain text and Hypertext Markup Language (HTML) versions of the same message. The character sequences CR (carriage return, "\r", U+000D), LF (line feed, "\n", U+000A), and CR/LF will be converted to CR/LF line breaks. Unpaired surrogate code points will be replaced with replacement characters.

Parameters:

• text - A string consisting of the plain text version of the message.

• html - A string consisting of the HTML version of the message.

Returns:

• This instance.

Throws:

• NullPointerException - The parameter text or html is null.

SetTextAndMarkdown

public Message SetTextAndMarkdown(String text, String markdown)

Sets the body of this message to a multipart body with plain text, Markdown, and Hypertext Markup Language (HTML) versions of the same message. The character sequences CR (carriage return, "\r", U+000D), LF (line feed, "\n", U+000A), and CR/LF will be converted to CR/LF line breaks. Unpaired surrogate code points will be replaced with replacement characters.

REMARK: The Markdown-to-HTML implementation currently supports all features of original Markdown, except that the implementation:

• does not strictly check the placement of "block-level HTML elements",
• does not prevent Markdown content from being interpreted as such merely because it's contained in a "block-level HTML element", and
• does not deliberately use HTML escapes to obfuscate email addresses wrapped in angle-brackets.

Adds an attachment to this message in the form of data from the given readable stream, and with the given media type. Before the new attachment is added, if this message isn't already a multipart message, it becomes a "multipart/mixed" message with the current body converted to an inline body part.

The following example (written in C# for the.NET version) is an extension method that adds an attachment from a byte array to a message.

public static Message AddAttachmentFromBytes(Message msg,
 byte[] bytes, MediaType mediaType) { {
MemoryStream fs = null;
try {
fs = new
 MemoryStream(bytes);
 return msg.AddAttachment(fs, mediaType);
}
finally {
try { if (fs != null) { fs.close(); } } catch (java.io.IOException ex) {}
}
} }

Adds an inline body part to this message in the form of data from the given readable stream, and with the given media type. Before the new body part is added, if this message isn't already a multipart message, it becomes a "multipart/mixed" message with the current body converted to an inline body part.

The following example (written in C# for the.NET version) is an extension method that adds an inline body part from a byte array to a message.

public static Message AddInlineFromBytes(Message msg,
 byte[] bytes, MediaType mediaType) { {
MemoryStream fs = null;
try {
fs = new
 MemoryStream(bytes);
 return msg.AddInline(fs, mediaType);
}
finally {
try { if (fs != null) { fs.close(); } } catch (java.io.IOException ex) {}
}
} }

@Deprecated public String ToMailtoUrl()

public static Message FromMailtoUri(String uri)

public static Message FromMailtoUri(URI uri)

public String ToMailtoUri()