Top Description Inners Fields Constructors Methods
jakarta.mail

public abstract Class Message

extends Object
implements Part
Class Inheritance
All Implemented Interfaces
jakarta.mail.Part
Known Direct Subclasses
jakarta.mail.internet.MimeMessage
Imports
jakarta.mail.search.SearchTerm, java.io.InvalidObjectException, .ObjectStreamException, .Serializable, java.util.Date
This class models an email message. This is an abstract class. Subclasses provide actual implementations.

Message implements the Part interface. Message contains a set of attributes and a "content". Messages within a folder also have a set of flags that describe its state within the folder.

Message defines some new attributes in addition to those defined in the Part interface. These attributes specify meta-data for the message - i.e., addressing and descriptive information about the message.

Message objects are obtained either from a Folder or by constructing a new Message object of the appropriate subclass. Messages that have been received are normally retrieved from a folder named "INBOX".

A Message object obtained from a folder is just a lightweight reference to the actual message. The Message is 'lazily' filled up (on demand) when each item is requested from the message. Note that certain folder implementations may return Message objects that are pre-filled with certain user-specified items. To send a message, an appropriate subclass of Message (e.g., MimeMessage) is instantiated, the attributes and content are filled in, and the message is sent using the Transport.send method.

Authors
John Mani, Bill Shannon, Max Spivak
See Also
jakarta.mail.Part

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
Message.RecipientType

This inner class defines the types of recipients allowed by the Message class.

Field Summary

Modifier and TypeField and Description
protected boolean
expunged

True if this message has been expunged.

protected Folder
folder

The containing folder, if this message is obtained from a folder

protected int
msgnum

The number of this message within its folder, or zero if the message was not retrieved from a folder.

protected Session
session

The Session object for this Message

Constructor Summary

AccessConstructor and Description
protected
Message()

No-arg version of the constructor.

protected
Message(Folder
containing folder
folder, int
this message's sequence number within this folder
msgnum)

Constructor that takes a Folder and a message number.

protected
Message(Session
A Session object
session)

Constructor that takes a Session.

Method Summary

Modifier and TypeMethod and Description
public abstract void
addFrom(Address[]
the senders
addresses)

Add these addresses to the existing "From" attribute

public void
addRecipient(Message.RecipientType
the recipient type
type, Address
the address
address)

Add this recipient address to the existing ones of the given type.

public abstract void
addRecipients(Message.RecipientType
the recipient type
type, Address[]
the addresses
addresses)

Add these recipient addresses to the existing ones of the given type.

public Address[]

Returns:

array of Address objects
getAllRecipients()

Get all the recipient addresses for the message.

public abstract Flags

Returns:

Flags object containing the flags for this message
getFlags()

Returns a Flags object containing the flags for this message.

public Folder

Returns:

the containing folder
getFolder()

Get the folder from which this message was obtained.

public abstract Address[]

Returns:

array of Address objects
getFrom()

Returns the "From" attribute.

public int

Returns:

the message number
getMessageNumber()

Get the Message number for this Message.

public abstract Date

Returns:

the date this message was received
getReceivedDate()

Get the date this message was received.

public abstract Address[]

Returns:

array of Address objects
getRecipients(Message.RecipientType
the recipient type
type)

Get all the recipient addresses of the given type.

public Address[]

Returns:

addresses to which replies should be directed
getReplyTo()

Get the addresses to which replies should be directed.

public abstract Date

Returns:

the date this message was sent
getSentDate()

Get the date this message was sent.

public Session

Returns:

the message's Session
getSession()

Return the Session used when this message was created.

public abstract String

Returns:

the subject
getSubject()

Get the subject of this message.

public boolean

Returns:

true if the message is expunged
isExpunged()

Checks whether this message is expunged.

public boolean

Returns:

value of the specified flag for this message
isSet(Flags.Flag
the flag
flag)

Check whether the flag specified in the flag argument is set in this message.

public boolean

Returns:

true if the Message matches this search criterion, false otherwise.
match(SearchTerm
the Search criterion
term)

Apply the specified Search criterion to this message.

public abstract Message

Returns:

the reply Message
reply(boolean
reply should be sent to all recipients of this message
replyToAll)

Get a new Message suitable for a reply to this message.

public abstract void
saveChanges()

Save any changes made to this message into the message-store when the containing folder is closed, if the message is contained in a folder.

protected void
setExpunged(boolean
the expunged flag
expunged)

Sets the expunged flag for this Message.

public void
setFlag(Flags.Flag
Flags.Flag object containing the flag to be set
flag, boolean
the value to be set
set)

Set the specified flag on this message to the specified value.

public abstract void
setFlags(Flags
Flags object containing the flags to be set
flag, boolean
the value to be set
set)

Set the specified flags on this message to the specified value.

public abstract void
setFrom()

Set the "From" attribute in this Message.

public abstract void
setFrom(Address
the sender
address)

Set the "From" attribute in this Message.

protected void
setMessageNumber(int
the message number
msgnum)

Set the Message number for this Message.

public void
setRecipient(Message.RecipientType
the recipient type
type, Address
the address
address)

Set the recipient address.

public abstract void
setRecipients(Message.RecipientType
the recipient type
type, Address[]
the addresses
addresses)

Set the recipient addresses.

public void
setReplyTo(Address[]
addresses to which replies should be directed
addresses)

Set the addresses to which replies should be directed.

public abstract void
setSentDate(Date
the sent date of this message
date)

Set the sent date of this message.

public abstract void
setSubject(String
the subject
subject)

Set the subject of this message.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

expungedback to summary
protected boolean expunged

True if this message has been expunged.

folderback to summary
protected Folder folder

The containing folder, if this message is obtained from a folder

msgnumback to summary
protected int msgnum

The number of this message within its folder, or zero if the message was not retrieved from a folder.

sessionback to summary
protected Session session

The Session object for this Message

Constructor Detail

Messageback to summary
protected Message()

No-arg version of the constructor.

Messageback to summary
protected Message(Folder folder, int msgnum)

Constructor that takes a Folder and a message number. Used by Folder implementations.

Parameters
folder:Folder

containing folder

msgnum:int

this message's sequence number within this folder

Messageback to summary
protected Message(Session session)

Constructor that takes a Session. Used for client created Message objects.

Parameters
session:Session

A Session object

Method Detail

addFromback to summary
public abstract void addFrom(Address[] addresses) throws MessagingException

Add these addresses to the existing "From" attribute

Parameters
addresses:Address[]

the senders

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values
IllegalStateException:
if this message is obtained from a READ_ONLY folder.
addRecipientback to summary
public void addRecipient(Message.RecipientType type, Address address) throws MessagingException

Add this recipient address to the existing ones of the given type.

The default implementation uses the addRecipients method.

Parameters
type:Message.RecipientType

the recipient type

address:Address

the address

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values
addRecipientsback to summary
public abstract void addRecipients(Message.RecipientType type, Address[] addresses) throws MessagingException

Add these recipient addresses to the existing ones of the given type.

Parameters
type:Message.RecipientType

the recipient type

addresses:Address[]

the addresses

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values
IllegalStateException:
if this message is obtained from a READ_ONLY folder.
getAllRecipientsback to summary
public Address[] getAllRecipients() throws MessagingException

Get all the recipient addresses for the message. The default implementation extracts the TO, CC, and BCC recipients using the getRecipients method.

This method returns null if none of the recipient headers are present in this message. It may Return an empty array if any recipient header is present, but contains no addresses.

Returns:Address[]

array of Address objects

Exceptions
MessagingException:
for failures
See Also
Message.RecipientType#TO, Message.RecipientType#CC, Message.RecipientType#BCC, getRecipients
getFlagsback to summary
public abstract Flags getFlags() throws MessagingException

Returns a Flags object containing the flags for this message.

Modifying any of the flags in this returned Flags object will not affect the flags of this message. Use setFlags() to do that.

Returns:Flags

Flags object containing the flags for this message

Exceptions
MessagingException:
for failures
See Also
jakarta.mail.Flags, setFlags
getFolderback to summary
public Folder getFolder()

Get the folder from which this message was obtained. If this is a new message or nested message, this method returns null.

Returns:Folder

the containing folder

getFromback to summary
public abstract Address[] getFrom() throws MessagingException

Returns the "From" attribute. The "From" attribute contains the identity of the person(s) who wished this message to be sent.

In certain implementations, this may be different from the entity that actually sent the message.

This method returns null if this attribute is not present in this message. Returns an empty array if this attribute is present, but contains no addresses.

Returns:Address[]

array of Address objects

Exceptions
MessagingException:
for failures
getMessageNumberback to summary
public int getMessageNumber()

Get the Message number for this Message. A Message object's message number is the relative position of this Message in its Folder. Note that the message number for a particular Message can change during a session if other messages in the Folder are deleted and expunged.

Valid message numbers start at 1. Messages that do not belong to any folder (like newly composed or derived messages) have 0 as their message number.

Returns:int

the message number

getReceivedDateback to summary
public abstract Date getReceivedDate() throws MessagingException

Get the date this message was received.

Returns:Date

the date this message was received

Exceptions
MessagingException:
for failures
getRecipientsback to summary
public abstract Address[] getRecipients(Message.RecipientType type) throws MessagingException

Get all the recipient addresses of the given type.

This method returns null if no recipients of the given type are present in this message. It may return an empty array if the header is present, but contains no addresses.

Parameters
type:Message.RecipientType

the recipient type

Returns:Address[]

array of Address objects

Exceptions
MessagingException:
for failures
See Also
Message.RecipientType#TO, Message.RecipientType#CC, Message.RecipientType#BCC
getReplyToback to summary
public Address[] getReplyTo() throws MessagingException

Get the addresses to which replies should be directed. This will usually be the sender of the message, but some messages may direct replies to a different address.

The default implementation simply calls the getFrom method.

This method returns null if the corresponding header is not present. Returns an empty array if the header is present, but contains no addresses.

Returns:Address[]

addresses to which replies should be directed

Exceptions
MessagingException:
for failures
See Also
getFrom
getSentDateback to summary
public abstract Date getSentDate() throws MessagingException

Get the date this message was sent.

Returns:Date

the date this message was sent

Exceptions
MessagingException:
for failures
getSessionback to summary
public Session getSession()

Return the Session used when this message was created.

Returns:Session

the message's Session

Since
JavaMail 1.5
getSubjectback to summary
public abstract String getSubject() throws MessagingException

Get the subject of this message.

Returns:String

the subject

Exceptions
MessagingException:
for failures
isExpungedback to summary
public boolean isExpunged()

Checks whether this message is expunged. All other methods except getMessageNumber() are invalid on an expunged Message object.

Messages that are expunged due to an explict expunge() request on the containing Folder are removed from the Folder immediately. Messages that are externally expunged by another source are marked "expunged" and return true for the isExpunged() method, but they are not removed from the Folder until an explicit expunge() is done on the Folder.

See the description of expunge() for more details on expunge handling.

Returns:boolean

true if the message is expunged

See Also
Folder#expunge
isSetback to summary
public boolean isSet(Flags.Flag flag) throws MessagingException

Check whether the flag specified in the flag argument is set in this message.

The default implementation uses getFlags.

Parameters
flag:Flags.Flag

the flag

Returns:boolean

value of the specified flag for this message

Exceptions
MessagingException:
for failures
See Also
jakarta.mail.Flags.Flag#ANSWERED, jakarta.mail.Flags.Flag#DELETED, jakarta.mail.Flags.Flag#DRAFT, jakarta.mail.Flags.Flag#FLAGGED, jakarta.mail.Flags.Flag#RECENT, jakarta.mail.Flags.Flag#SEEN, jakarta.mail.Flags.Flag
matchback to summary
public boolean match(SearchTerm term) throws MessagingException

Apply the specified Search criterion to this message.

Parameters
term:SearchTerm

the Search criterion

Returns:boolean

true if the Message matches this search criterion, false otherwise.

Exceptions
MessagingException:
for failures
See Also
jakarta.mail.search.SearchTerm
replyback to summary
public abstract Message reply(boolean replyToAll) throws MessagingException

Get a new Message suitable for a reply to this message. The new Message will have its attributes and headers set up appropriately. Note that this new message object will be empty, that is, it will not have a "content". These will have to be suitably filled in by the client.

If replyToAll is set, the new Message will be addressed to all recipients of this message. Otherwise, the reply will be addressed to only the sender of this message (using the value of the getReplyTo method).

The "Subject" field is filled in with the original subject prefixed with "Re:" (unless it already starts with "Re:").

The reply message will use the same session as this message.

Parameters
replyToAll:boolean

reply should be sent to all recipients of this message

Returns:Message

the reply Message

Exceptions
MessagingException:
for failures
saveChangesback to summary
public abstract void saveChanges() throws MessagingException

Save any changes made to this message into the message-store when the containing folder is closed, if the message is contained in a folder. (Some implementations may save the changes immediately.) Update any header fields to be consistent with the changed message contents. If any part of a message's headers or contents are changed, saveChanges must be called to ensure that those changes are permanent. If saveChanges is not called, any such modifications may or may not be saved, depending on the message store and folder implementation.

Messages obtained from folders opened READ_ONLY should not be modified and saveChanges should not be called on such messages.

Exceptions
MessagingException:
for other failures
IllegalStateException:
if this message is obtained from a READ_ONLY folder.
IllegalWriteException:
if the underlying implementation does not support modification of existing values.
setExpungedback to summary
protected void setExpunged(boolean expunged)

Sets the expunged flag for this Message. This method is to be used only by the implementation classes.

Parameters
expunged:boolean

the expunged flag

setFlagback to summary
public void setFlag(Flags.Flag flag, boolean set) throws MessagingException

Set the specified flag on this message to the specified value. This will result in a MessageChangedEvent being delivered to any MessageChangedListener registered on this Message's containing folder.

The default implementation uses the setFlags method.

Parameters
flag:Flags.Flag

Flags.Flag object containing the flag to be set

set:boolean

the value to be set

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values.
IllegalStateException:
if this message is obtained from a READ_ONLY folder.
See Also
jakarta.mail.event.MessageChangedEvent
setFlagsback to summary
public abstract void setFlags(Flags flag, boolean set) throws MessagingException

Set the specified flags on this message to the specified value. Note that any flags in this message that are not specified in the given Flags object are unaffected.

This will result in a MessageChangedEvent being delivered to any MessageChangedListener registered on this Message's containing folder.

Parameters
flag:Flags

Flags object containing the flags to be set

set:boolean

the value to be set

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values.
IllegalStateException:
if this message is obtained from a READ_ONLY folder.
See Also
jakarta.mail.event.MessageChangedEvent
setFromback to summary
public abstract void setFrom() throws MessagingException

Set the "From" attribute in this Message. The value of this attribute is obtained from the property "mail.user". If this property is absent, the system property "user.name" is used.

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values
IllegalStateException:
if this message is obtained from a READ_ONLY folder.
setFromback to summary
public abstract void setFrom(Address address) throws MessagingException

Set the "From" attribute in this Message.

Parameters
address:Address

the sender

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values
IllegalStateException:
if this message is obtained from a READ_ONLY folder.
setMessageNumberback to summary
protected void setMessageNumber(int msgnum)

Set the Message number for this Message. This method is invoked only by the implementation classes.

Parameters
msgnum:int

the message number

setRecipientback to summary
public void setRecipient(Message.RecipientType type, Address address) throws MessagingException

Set the recipient address. All addresses of the specified type are replaced by the address parameter.

The default implementation uses the setRecipients method.

Parameters
type:Message.RecipientType

the recipient type

address:Address

the address

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values
setRecipientsback to summary
public abstract void setRecipients(Message.RecipientType type, Address[] addresses) throws MessagingException

Set the recipient addresses. All addresses of the specified type are replaced by the addresses parameter.

Parameters
type:Message.RecipientType

the recipient type

addresses:Address[]

the addresses

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values
IllegalStateException:
if this message is obtained from a READ_ONLY folder.
setReplyToback to summary
public void setReplyTo(Address[] addresses) throws MessagingException

Set the addresses to which replies should be directed. (Normally only a single address will be specified.) Not all message types allow this to be specified separately from the sender of the message.

The default implementation provided here just throws the MethodNotSupportedException.

Parameters
addresses:Address[]

addresses to which replies should be directed

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values
IllegalStateException:
if this message is obtained from a READ_ONLY folder.
MethodNotSupportedException:
if the underlying implementation does not support setting this attribute
setSentDateback to summary
public abstract void setSentDate(Date date) throws MessagingException

Set the sent date of this message.

Parameters
date:Date

the sent date of this message

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values
IllegalStateException:
if this message is obtained from a READ_ONLY folder.
setSubjectback to summary
public abstract void setSubject(String subject) throws MessagingException

Set the subject of this message.

Parameters
subject:String

the subject

Exceptions
MessagingException:
for other failures
IllegalWriteException:
if the underlying implementation does not support modification of existing values
IllegalStateException:
if this message is obtained from a READ_ONLY folder.
jakarta.mail back to summary

public Class Message.RecipientType

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Known Direct Subclasses
jakarta.mail.internet.MimeMessage.RecipientType
This inner class defines the types of recipients allowed by the Message class. The currently defined types are TO, CC and BCC. Note that this class only has a protected constructor, thereby restricting new Recipient types to either this class or subclasses. This effectively implements an enumeration of the allowed Recipient types. The following code sample shows how to use this class to obtain the "TO" recipients from a message. 

Message msg = folder.getMessages(1);
Address[] a = m.getRecipients(Message.RecipientType.TO);
See Also
jakarta.mail.Message#getRecipients, jakarta.mail.Message#setRecipients, jakarta.mail.Message#addRecipients

Field Summary

Modifier and TypeField and Description
public static final Message.RecipientType
BCC

The "Bcc" (blind carbon copy) recipients.

public static final Message.RecipientType
CC

The "Cc" (carbon copy) recipients.

private static final long
serialVersionUID

public static final Message.RecipientType
TO

The "To" (primary) recipients.

protected String
type

The type of recipient, usually the name of a corresponding Internet standard header.

Constructor Summary

AccessConstructor and Description
protected
RecipientType(String
the recipient type
type)

Constructor for use by subclasses.

Method Summary

Modifier and TypeMethod and Description
protected Object

Returns:

the RecipientType object instance
readResolve()

When deserializing a RecipientType, we need to make sure to return only one of the known static final instances defined in this class.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

BCCback to summary
public static final Message.RecipientType BCC

The "Bcc" (blind carbon copy) recipients.

CCback to summary
public static final Message.RecipientType CC

The "Cc" (carbon copy) recipients.

serialVersionUIDback to summary
private static final long serialVersionUID
TOback to summary
public static final Message.RecipientType TO

The "To" (primary) recipients.

typeback to summary
protected String type

The type of recipient, usually the name of a corresponding Internet standard header.

Constructor Detail

RecipientTypeback to summary
protected RecipientType(String type)

Constructor for use by subclasses.

Parameters
type:String

the recipient type

Method Detail

readResolveback to summary
protected Object readResolve() throws ObjectStreamException

When deserializing a RecipientType, we need to make sure to return only one of the known static final instances defined in this class. Subclasses must implement their own readResolve method that checks for their known instances before calling this super method.

Returns:Object

the RecipientType object instance

Exceptions
ObjectStreamException:
for object stream errors
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations
@Override