NAME

Mail::Box::Message - manage one message within a mail-folder

CLASS INHERITANCE

 Mail::Box::Message
   is a Mail::Message
   is a Mail::Reporter

 Mail::Box::Message is extended by
   Mail::Box::Dir::Message
   Mail::Box::File::Message
   Mail::Box::Net::Message

SYNOPSIS

 # Usually these message objects are created indirectly
 use Mail::Box::Manager;
 my $manager = Mail::Box::Manager->new;
 my $folder  = $manager->open(folder => 'Mail/Drafts');
 my $msg     = $folder->message(1);
 $msg->delete;
 $msg->size;   # and much more

DESCRIPTION

These pages do only describe methods which relate to folders. If you access the knowledge of a message, then read Mail::Message.

During its life, a message will pass through certain stages. These stages were introduced to reduce the access-time to the folder. Changing from stage, the message's body and head objects may change.

METHODS

Initiation

new OPTIONS

(Class method)

 OPTION               DEFAULT
 body                 undef
 body_type            <from folder>
 deleted              <false>
 field_type           undef
 folder               <required>
 head                 undef
 head_type            'Mail::Message::Head::Complete'
 log                  'WARNINGS'
 messageId            undef
 modified             <false>
 size                 undef
 trace                'WARNINGS'
 trusted              <false>

body => OBJECT: See Mail::Message::new(body)
body_type => CODE|CLASS: If the body of a message is used delay-loaded, the message must what type of message to become when it finally gets parsed. The folder which is delaying the load must specify the algorithm to determine that type.
deleted => BOOLEAN: Is the file deleted from the start?
field_type => CLASS: See Mail::Message::new(field_type)
folder => FOLDER: (obligatory) The folder where this message appeared in. The argument is an instance of (a sub-class of) a Mail::Box.
head => OBJECT: See Mail::Message::new(head)
head_type => CLASS: See Mail::Message::new(head_type)
log => LEVEL: See Mail::Reporter::new(log)
messageId => STRING: See Mail::Message::new(messageId)
modified => BOOLEAN: See Mail::Message::new(modified)
size => INTEGER: The size of the message, which includes head and body, but without the message separators which may be used by the folder type.
trace => LEVEL: See Mail::Reporter::new(trace)
trusted => BOOLEAN: See Mail::Message::new(trusted)

Constructing a Message

bounce [RG-OBJECT|OPTIONS]: See Mail::Message::Construct::bounce()
build [MESSAGE|BODY], CONTENT: See Mail::Message::Construct::build()
buildFromBody BODY, [HEAD], HEADERS: See Mail::Message::Construct::buildFromBody()
coerce MESSAGE: Coerce a message to be included in a folder. The folder itself is not specified, but the type of the message is transformed correctly. The coerced version of the message is returned. When no changes had to be made, the original message is returned.
forward OPTIONS: See Mail::Message::Construct::forward()
forwardPostlude: See Mail::Message::Construct::forwardPostlude()
forwardPrelude: See Mail::Message::Construct::forwardPrelude()
forwardSubject STRING: See Mail::Message::Construct::forwardSubject()
read FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES, OPTIONS: See Mail::Message::Construct::read()
reply OPTIONS: See Mail::Message::Construct::reply()
replyPrelude [STRING|FIELD|ADDRESS]: See Mail::Message::Construct::replyPrelude()
replySubject STRING: See Mail::Message::Construct::replySubject()

The Message

clone

See Mail::Message::clone()

container

See Mail::Message::container()

copyTo FOLDER

Copy the message to the indicated opened FOLDER, without deleting the original. The coerced message (the copy in the desitnation folder) is returned.

Examples:

 my $draft = $mgr->open(folder => 'Draft');
 $message->copyTo($draft);

folder [FOLDER]

In with folder did we detect this message/dummy? This is a reference to the folder-object.

isDummy

See Mail::Message::isDummy()

isModified

See Mail::Message::isModified()

isPart

See Mail::Message::isPart()

messageId

See Mail::Message::messageId()

modified [BOOLEAN]

See Mail::Message::modified()

moveTo FOLDER

Move the message from this folder to the FOLDER specified. This will create a copy (using clone()) first, and flag this original message to be deleted. So until the source folder is closed, two copies of the message stay in memory. The newly created message (part of the destination folder) is returned.

print [FILEHANDLE]

See Mail::Message::print()

send [MAILER], OPTIONS

See Mail::Message::send()

seqnr [INTEGER]

Get the number of this message is the current folder. It starts counting from zero. Do not change the number.

size

See Mail::Message::size()

toplevel

See Mail::Message::toplevel()

write [FILEHANDLE]

See Mail::Message::write()

The Header

head [HEAD]: See Mail::Message::head()

Header Shortcuts

bcc: See Mail::Message::bcc()
cc: See Mail::Message::cc()
date: See Mail::Message::date()
destinations: See Mail::Message::destinations()
from: See Mail::Message::from()
get FIELD: See Mail::Message::get()
guessTimestamp: See Mail::Message::guessTimestamp()
nrLines: See Mail::Message::nrLines()
sender: See Mail::Message::sender()
subject: See Mail::Message::subject()
timestamp: See Mail::Message::timestamp()
to: See Mail::Message::to()

The Body

body [BODY]: See Mail::Message::body()
decoded OPTIONS: See Mail::Message::decoded()
encode OPTIONS: See Mail::Message::encode()
isMultipart: See Mail::Message::isMultipart()
parts ['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER]: See Mail::Message::parts()

Access to the Message

file: See Mail::Message::Construct::file()
lines: See Mail::Message::Construct::lines()
string: See Mail::Message::Construct::string()

Labels

delete

Flag the message to be deleted. The real deletion only takes place on a synchronization of the folder. See deleted().

The time stamp of the moment of deletion is stored as value. When the same message is deleted more than once, the first time stamp will stay.

Examples:

 $message->delete;
 $message->deleted(1);  # exactly the same
 delete $message;

deleted [BOOLEAN]

Set the delete flag for this message. Without argument, the method returns the same is the isDeleted() method, which is prefered. When a true value is given, delete() is called.

Examples:

 $message->deleted(1);          # delete
 $message->delete;              # delete (prefered)

 $message->deleted(0);          # undelete

 if($message->deleted) {...}    # check
 if($message->isDeleted) {...}  # check (prefered)

isDeleted

Returns the moment (as the time function returns) when the message was flagged for deletion, or undef when the message is not deleted.

Examples:

 next if $message->isDeleted;

 if(my $when = $message->isDeleted) {
    print scalar localtime $when;
 }

label LABEL [,VALUE [LABEL, VALUE] ]

See Mail::Message::label()

labels

See Mail::Message::labels()

labelsToStatus

See Mail::Message::labelsToStatus()

statusToLabels

See Mail::Message::statusToLabels()

Reading and Writing [internals]

DESTROY

See Mail::Message::DESTROY()

diskDelete

Remove a message from disk. This is not from the folder, but everything else, like parts of the message which are stored externally from the folder.

isDelayed

See Mail::Message::isDelayed()

readBody PARSER, HEAD [, BODYTYPE]

Read the body of one message. The PARSER gives access to the folder file. The HEAD has been read with readHead(). The optional BODYTYPE supplies the class name of the body to be created, or a code reference to a routine which can produce a body type based on the head (passed as first argument).

By default, the BODYTYPE will call Mail::Box::determineBodyType() where the message will be added to.

readFromParser PARSER, [BODYTYPE]

See Mail::Message::readFromParser()

readHead PARSER [,CLASS]

See Mail::Message::readHead()

storeBody BODY

See Mail::Message::storeBody()

takeMessageId [STRING]

See Mail::Message::takeMessageId()

Logging and Tracing

defaultTrace [LEVEL, [LEVEL]: See Mail::Reporter::defaultTrace()
errors: See Mail::Reporter::errors()
log [LEVEL [,STRINGS]]: See Mail::Reporter::log()
printStructure [FILEHANDLE][, INDENT]: See Mail::Message::Construct::printStructure()
report [LEVEL]: See Mail::Reporter::report()
reportAll [LEVEL]: See Mail::Reporter::reportAll()
shortString: Convert the message header to a short string, representing the most important facts (for debugging purposes only).
trace [LEVEL]: See Mail::Reporter::trace()
warnings: See Mail::Reporter::warnings()

Other Methods

AUTOLOAD: See Mail::Reporter::AUTOLOAD()
inGlobalDestruction: See Mail::Reporter::inGlobalDestruction()
logPriority LEVEL: See Mail::Reporter::logPriority()
logSettings: See Mail::Reporter::logSettings()
notImplemented: See Mail::Reporter::notImplemented()

AUTHOR

Written by Mark Overmeer (mark@overmeer.net) with the help of many. See the ChangeLog for details.

VERSION

This code is beta, version 2.038.

To install Mail::Box, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mail::Box

CPAN shell

perl -MCPAN -e shell
install Mail::Box

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

CLASS INHERITANCE

SYNOPSIS

DESCRIPTION

METHODS

Initiation

Constructing a Message

The Message

The Header

Header Shortcuts

The Body

Access to the Message

Labels

Reading and Writing [internals]

Logging and Tracing

Other Methods

SEE ALSO

AUTHOR

VERSION

Module Install Instructions