NAME

Mail::Exchange::Message - class to deal with .msg files, used by Microsoft Exchange / MS Outlook.

SYNOPSIS

use Mail::Exchange::Message;
use Mail::Exchange::Message::MessageFlags;
use Mail::Exchange::Recipient;
use Mail::Exchange::PidTagIDs;

# modify an existing .msg file

my $msg=Mail::Exchange::Message->new("my.msg");
print "old Subject: ", $msg->get(PidTagSubject), "\n";
$msg->setSubject('new subject');
$msg->save("changed.msg");

# create a .msg file from scratch, and send it to
# the browser from a CGI script

my $msg=Mail::Exchange::Message->new();
$msg->setUnicode(1);
$msg->setSubject('message subject');
$msg->setBody('message body');
$msg->set(PidTagMessageFlags, mfUnsent);
$message->setDisplayTo('test@somewhere.com');

my $recipient=Mail::Exchange::Recipient->new();
$recipient->setEmailAddress('test@somewhere.com');
$recipient->setDisplayName('John Tester');
$recipient->setRecipientType('To');
$message->addRecipient($recipient);

binmode(STDOUT);
print STDOUT qq(Content-type: application/vnd.ms-outlook
Content-Disposition: attachment; filename="newmessage.msg"

);

$message->save(\*STDOUT);

DESCRIPTION

Mail::Exchange::Message allows you to read and write binary message files that Microsoft Outlook uses to store emails, to-dos, appointments and so on. It does not need Windows, or Outlook, installed, and should be able to run on any operating system that supports perl.

It might have been named "Outlook" instead of "Exchange", but the "Mail::Outlook" and "Email::Outlook" namespaces had both been taken at the time of its implementation, and it contains some sub-modules that might be helpful to implementations of more functionality with Microsoft Exchange, with which it is intended to coexist.

new()

$msg=Mail::Exchange::Message->new([$file])

Read a message from the .msg file $file, or create a new, empty one, if $file isn't given.

parse()

$msg->parse($file)

Read a message file into an internal structure. Called from new() if a filename argument is given. $file is expected to be a string, but may be anything that is accepted by OLE::Storage_Lite.

set()

$msg->set($tag, $value, [$flags,] [$type,] [$guid])

Set a property within a message. $tag can be any numeric property defined in Mail::Exchange::PidTagIDs.pm, a numeric named property defined in Mail::Exchange::PidLidIDs.pm, or a string property. $value is the value the property is set to.

$flags is a bit-wise or of 1 (this property is mandatory and must not be deleted), 2 (property is writable) and 4 (property is readable and may be displayed to the user). Default is 6.

When a string named property is defined for the first time, its $type and $guid must be given as well, as stated [MS-OXPROPS], section 1.3.2

setSender()

$msg->setSender($address)

setSender is a shortcut for setting various properties that descripe the sender of a message.

setDisplayTo()

$msg->setDisplayTo($text)

setDisplayTo sets the recipient list that is shown by outlook in the "To:" address line.

setDisplayCc()

$msg->setDisplayCc($text)

setDisplayCc sets the recipient list that is shown by outlook in the "Cc:" address line.

setDisplayBcc()

$msg->setDisplayBcc($text)

setDisplayBcc sets the recipient list that is shown by outlook in the "Bcc:" address line.

setSubject()

$msg->setSubject($text)

setSubject sets the subject of the message by setting various internal properties.

setBody()

$msg->setBody($text)

setBody sets the plain text body of the message.

setRtfBody()

setRtfBody($text[, $compress])

setRtfBody sets the rich text format body of the message.

The message file format allows for compressed or uncompressed rtf storage. If $compress is set, $text will be compressed before being stored. (As of now, $compress is not implemented, and $text will always be stored in uncompressed form).

getRtfBody()

$msg->getRtfBody()

getRtfBody gets the RTF Body of a message, uncompressing it if neccesary.

setHtmlBody()

$msg->setHtmlBody($htmltext)

setHtmlBody sets the html version of the message body. It is a shortcut for $msg-set(PidTagHtml, $htmltext)>.

setUnicode()

$msg->setUnicode($flag)

If $flag is 0, all strings within the message will be stored one byte per character. If $flag is 1, strings will be stored in what's called unicode in the documentation (actually, UCS2LE encoded strings, using 2 bytes per character).

save()

save($msgfile)

Saves a message object to a file. $msgfile may be a file, or anything else that OLE::Storage_Lite accepts.

addattachment()

addattachment($object)

Adds a Mail::Exchange::Attachment object to a message. Not implemented yet.

addrecipient()

addrecipient($object)

Adds a Mail::Exchange::Recipient object to a message.

WARNING

This Module is quite alpha. It reads most msg files ok, and writing some .msg files works, but there are several features that aren't implemented yet, and using generated .msg files may have any adverse effects on Outlook, including program crashes.

COPYRIGHT

The Mail::Exchange modules are Copyright (c) 2012 Guntram Blohm. All rights reserverd.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

The Name definitions in Mail::Message::PidTagIDs.pm, Mail::Message::PidTagDefs.pm, Mail::Message::PidLidIDs.pm and Mail::Message::PropertyTypes.pm are taken from [MS-OXPROPS], which states

Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you may make copies of it in order to develop implementations of the technologies described in the Open Specifications and may distribute portions of it in your implementations using these technologies or your documentation as necessary to properly document the implementation. You may also distribute in your implementation, with or without modification, any schema, IDL’s, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications.

The compression/decompression algorithm for RTF content is described in [MS-OXRTFCP], which has the same copyright statement.

AUTHOR

Guntram Blohm gbl@bso2001.com

REFERENCES

[MS-OXPROPS] Exchange Server Protocols Master Property List, http://msdn.microsoft.com/en-us/library/cc433490(v=exchg.80).aspx on Sep 30, 2012

[MS-OXRTFCP] Rich Text Format (RTF) Compression Algorithm http://msdn.microsoft.com/en-us/library/cc463890(v=exchg.80).aspx on Sep 30, 2012

[MS-OXMSG]: Outlook Item (.msg) File Format http://msdn.microsoft.com/en-us/library/cc463912(v=exchg.80).aspx on Sep 30, 2012

cpanm Mail::Exchange::Message

perl -MCPAN -e shell
install Mail::Exchange::Message