Class MAPIMessage

All Implemented Interfaces:
Closeable, AutoCloseable

public class MAPIMessage extends POIReadOnlyDocument
Reads an Outlook MSG File in and provides hooks into its data structure. If you want to develop with HSMF, you might find it worth getting some of the Microsoft public documentation, such as: [MS-OXCMSG]: Message and Attachment Object Protocol Specification
  • Constructor Details

    • MAPIMessage

      public MAPIMessage()
      Constructor for creating new files.
    • MAPIMessage

      public MAPIMessage(String filename) throws IOException
      Constructor for reading MSG Files from the file system.
      Parameters:
      filename - Name of the file to read
      Throws:
      IOException - on errors reading, or invalid data
    • MAPIMessage

      public MAPIMessage(File file) throws IOException
      Constructor for reading MSG Files from the file system.
      Parameters:
      file - The file to read from
      Throws:
      IOException - on errors reading, or invalid data
    • MAPIMessage

      public MAPIMessage(InputStream in) throws IOException
      Constructor for reading MSG Files from an input stream.

      Note - this will buffer the whole message into memory in order to process. For lower memory use, use MAPIMessage(File)

      Parameters:
      in - The InputStream to buffer then read from
      Throws:
      IOException - on errors reading, or invalid data
    • MAPIMessage

      public MAPIMessage(POIFSFileSystem fs) throws IOException
      Constructor for reading MSG Files from a POIFS filesystem
      Parameters:
      fs - Open POIFS FileSystem containing the message
      Throws:
      IOException - on errors reading, or invalid data
    • MAPIMessage

      public MAPIMessage(DirectoryNode poifsDir) throws IOException
      Constructor for reading MSG Files from a certain point within a POIFS filesystem
      Parameters:
      poifsDir - Directory containing the message
      Throws:
      IOException - on errors reading, or invalid data
  • Method Details

    • getStringFromChunk

      public String getStringFromChunk(StringChunk chunk) throws ChunkNotFoundException
      Gets a string value based on the passed chunk.
      Throws:
      ChunkNotFoundException - if the chunk isn't there
    • getTextBody

      public String getTextBody() throws ChunkNotFoundException
      Gets the plain text body of this Outlook Message
      Returns:
      The string representation of the 'text' version of the body, if available.
      Throws:
      ChunkNotFoundException - If the text-body chunk does not exist and returnNullOnMissingChunk is set
    • getHtmlBody

      public String getHtmlBody() throws ChunkNotFoundException
      Gets the html body of this Outlook Message, if this email contains a html version.
      Returns:
      The string representation of the 'html' version of the body, if available.
      Throws:
      ChunkNotFoundException - If the html-body chunk does not exist and returnNullOnMissingChunk is set
    • getRtfBody

      public String getRtfBody() throws ChunkNotFoundException
      Gets the RTF Rich Message body of this Outlook Message, if this email contains a RTF (rich) version.
      Returns:
      The string representation of the 'RTF' version of the body, if available.
      Throws:
      ChunkNotFoundException - If the rtf-body chunk does not exist and returnNullOnMissingChunk is set
    • getSubject

      public String getSubject() throws ChunkNotFoundException
      Gets the subject line of the Outlook Message
      Throws:
      ChunkNotFoundException - If the subject-chunk does not exist and returnNullOnMissingChunk is set
    • getDisplayFrom

      public String getDisplayFrom() throws ChunkNotFoundException
      Gets the display value of the "FROM" line of the outlook message This is not the actual address that was sent from but the formated display of the user name.
      Throws:
      ChunkNotFoundException - If the from-chunk does not exist and returnNullOnMissingChunk is set
    • getDisplayTo

      public String getDisplayTo() throws ChunkNotFoundException
      Gets the display value of the "TO" line of the outlook message. If there are multiple recipients, they will be separated by semicolons. This is not the actual list of addresses/values that will be sent to if you click Reply in the email - those are stored in RecipientChunks.
      Throws:
      ChunkNotFoundException - If the to-chunk does not exist and returnNullOnMissingChunk is set
    • getDisplayCC

      public String getDisplayCC() throws ChunkNotFoundException
      Gets the display value of the "CC" line of the outlook message. If there are multiple recipients, they will be separated by semicolons. This is not the actual list of addresses/values that will be sent to if you click Reply in the email - those are stored in RecipientChunks.
      Throws:
      ChunkNotFoundException - If the cc-chunk does not exist and returnNullOnMissingChunk is set
    • getDisplayBCC

      public String getDisplayBCC() throws ChunkNotFoundException
      Gets the display value of the "BCC" line of the outlook message. If there are multiple recipients, they will be separated by semicolons. This is not the actual list of addresses/values that will be sent to if you click Reply in the email - those are stored in RecipientChunks. This will only be present in sent emails, not received ones!
      Throws:
      ChunkNotFoundException - If the bcc-chunk does not exist and returnNullOnMissingChunk is set
    • getRecipientEmailAddress

      public String getRecipientEmailAddress() throws ChunkNotFoundException
      Returns all the recipients' email address, separated by semicolons. Checks all the likely chunks in search of the addresses.
      Throws:
      ChunkNotFoundException
    • getRecipientEmailAddressList

      public String[] getRecipientEmailAddressList() throws ChunkNotFoundException
      Returns an array of all the recipient's email address, normally in TO then CC then BCC order. Checks all the likely chunks in search of the addresses.
      Throws:
      ChunkNotFoundException
    • getRecipientNames

      public String getRecipientNames() throws ChunkNotFoundException
      Returns all the recipients' names, separated by semicolons. Checks all the likely chunks in search of the names. See also getDisplayTo(), getDisplayCC() and getDisplayBCC().
      Throws:
      ChunkNotFoundException
    • getRecipientNamesList

      public String[] getRecipientNamesList() throws ChunkNotFoundException
      Returns an array of all the recipient's names, normally in TO then CC then BCC order. Checks all the likely chunks in search of the names. See also getDisplayTo(), getDisplayCC() and getDisplayBCC().
      Throws:
      ChunkNotFoundException
    • guess7BitEncoding

      public void guess7BitEncoding()
      Tries to identify the correct encoding for 7-bit (non-unicode) strings in the file.

      Many messages store their strings as unicode, which is nice and easy. Some use one-byte encodings for their strings, but don't always store the encoding anywhere helpful in the file.

      This method checks for codepage properties, and failing that looks at the headers for the message, and uses these to guess the correct encoding for your file.

      Bug #49441 has more on why this is needed

    • set7BitEncoding

      public void set7BitEncoding(String charset)
      Many messages store their strings as unicode, which is nice and easy. Some use one-byte encodings for their strings, but don't easily store the encoding anywhere in the file! If you know what the encoding is of your file, you can use this method to set the 7 bit encoding for all the non unicode strings in the file.
      See Also:
    • has7BitEncodingStrings

      public boolean has7BitEncodingStrings()
      Does this file contain any strings that are stored as 7 bit rather than unicode?
    • getHeaders

      public String[] getHeaders() throws ChunkNotFoundException
      Returns all the headers, one entry per line
      Throws:
      ChunkNotFoundException
    • getConversationTopic

      public String getConversationTopic() throws ChunkNotFoundException
      Gets the conversation topic of the parsed Outlook Message. This is the part of the subject line that is after the RE: and FWD:
      Throws:
      ChunkNotFoundException - If the conversation-topic chunk does not exist and returnNullOnMissingChunk is set
    • getMessageClassEnum

      public MAPIMessage.MESSAGE_CLASS getMessageClassEnum() throws ChunkNotFoundException
      Gets the message class of the parsed Outlook Message. (Yes, you can use this to determine if a message is a calendar item, note, or actual outlook Message) For emails the class will be IPM.Note
      Throws:
      ChunkNotFoundException - If the message-class chunk does not exist and returnNullOnMissingChunk is set
    • getMessageDate

      public Calendar getMessageDate() throws ChunkNotFoundException
      Gets the date that the message was accepted by the server on.
      Throws:
      ChunkNotFoundException
    • getMainChunks

      public Chunks getMainChunks()
      Gets the main, core details chunks
    • getRecipientDetailsChunks

      public RecipientChunks[] getRecipientDetailsChunks()
      Gets all the recipient details chunks. These will normally be in the order of: * TO recipients, in the order returned by getDisplayTo() * CC recipients, in the order returned by getDisplayCC() * BCC recipients, in the order returned by getDisplayBCC()
    • getNameIdChunks

      public NameIdChunks getNameIdChunks()
      Gets the Name ID chunks, or null if there aren't any
    • getAttachmentFiles

      public AttachmentChunks[] getAttachmentFiles()
      Gets the message attachments.
    • isReturnNullOnMissingChunk

      public boolean isReturnNullOnMissingChunk()
      Will you get a null on a missing chunk, or a ChunkNotFoundException (default is the exception).
    • setReturnNullOnMissingChunk

      public void setReturnNullOnMissingChunk(boolean returnNullOnMissingChunk)
      Sets whether on asking for a missing chunk, you get back null or a ChunkNotFoundException (default is the exception).