Introduction¶ ↑

Generally, the goal of the project is to enable the conversion of msg and pst files into standards based formats, without reliance on outlook, or any platform dependencies. In fact its currently pure ruby, so it should be easy to get running.

It is targeted at people who want to migrate their PIM data from outlook, converting msg and pst files into rfc2822 emails, vCard contacts, iCalendar appointments etc. However, it also aims to be a fairly complete mapi message store manipulation library, providing a sane model for (currently read-only) access to msg and pst files (message stores).

I am happy to accept patches, give commit bits etc.

Please let me know how it works for you, any feedback would be welcomed.

Features¶ ↑

Broad features of the project:

• Can be used as a general mapi library, where conversion to and working on a standard format doesn’t make sense.

• Supports conversion of messages to standard formats, like rfc2822 emails, vCard, etc.

• Well commented, and easily extended.

• Basic RTF converter, for providing a readable body when only RTF exists (needs work)

• RTF decompression support included, as well as HTML extraction from RTF where appropriate (both in pure ruby, see lib/mapi/rtf.rb)

• Support for mapping property codes to symbolic names, with many included.

Features of the msg format message store:

• Most key .msg structures are understood, and the only the parsing code should require minor tweaks. Most of remaining work is in achieving high-fidelity conversion to standards formats (see [TODO]).

• Supports both types of property storage (large ones in substg files, and small ones in the properties file.

• Complete support for named properties in different GUID namespaces.

• Initial support for handling embedded ole files, converting nested .msg files to message/rfc822 attachments, and serializing others as ole file attachments (allows you to view embedded excel for example).

Features of the pst format message store:

• Handles both Outlook 1997 & 2003 format pst files, both with no- and “compressible-” encryption.

• Understanding of the file format is still very superficial.

Usage¶ ↑

At the command line, it is simple to convert individual msg or pst files to .eml, or to convert a batch to an mbox format file. See mapitool help for details:

mapitool -si some_email.msg > some_email.eml
mapitool -s *.msg > mbox

There is also a fairly complete and easy to use high level library access:

require 'mapi/msg'

msg = Mapi::Msg.open filename

# access to the 3 main data stores, if you want to poke with the msg
# internals
msg.recipients
# => [#<Recipient:'\'Marley, Bob\' <bob.marley@gmail.com>'>]
msg.attachments
# => [#<Attachment filename='blah1.tif'>, #<Attachment filename='blah2.tif'>]
msg.properties
# => #<Properties ... normalized_subject='Testing' ...
# creation_time=#<DateTime: 2454042.45074714,0,2299161> ...>

To completely abstract away all msg peculiarities, convert the msg to a mime object. The message as a whole, and some of its main parts support conversion to mime objects.

msg.attachments.first.to_mime
# => #<Mime content_type='application/octet-stream'>
mime = msg.to_mime
puts mime.to_tree
# =>
- #<Mime content_type='multipart/mixed'>
  |- #<Mime content_type='multipart/alternative'>
  |  |- #<Mime content_type='text/plain'>
  |  \- #<Mime content_type='text/html'>
  |- #<Mime content_type='application/octet-stream'>
  \- #<Mime content_type='application/octet-stream'>

# convert mime object to serialised form,
# inclusive of attachments etc. (not ideal in memory, but its wip).
puts mime.to_s

Thanks¶ ↑

• The initial implementation of parsing msg files was based primarily on msgconvert.pl.

• The basis for the outlook 97 pst file was the source to libpst.

• The code for rtf decompression was implemented by inspecting the algorithm used in the JTNEF project.

Other¶ ↑

For more information, see

• TODO

• MsgDetails

• PstDetails

• OleDetails