perldoc > Mail::Message

📛 NAME

Mail::Message - general message object

🚀 Quick Reference

Use CaseCommandDescription
Open a folder and get a messagemy $mgr = Mail::Box::Manager->new; my $folder = $mgr->open(folder => 'InBox'); my $msg = $folder->message(2);Initialize a Mail::Box::Manager, open a folder, retrieve a message by index.
Get message subject$msg->subjectGet the subject of the message.
Get CC addresses$msg->ccGet list of Mail::Address objects from CC header.
Get decoded body$msg->decodedGet the decoded body of the message.
Send a simple emailMail::Message->build(...)->send(via => 'postfix');Build and send a message using a transport agent.
Reply to a messageMail::Message->reply(...)Create a reply message.
Forward a messageMail::Message->forward(...)Create a forward message.

🔗 INHERITANCE

📝 SYNOPSIS

use Mail::Box::Manager;
my $mgr    = Mail::Box::Manager->new;
my $folder = $mgr->open(folder => 'InBox');
my $msg    = $folder->message(2);    # $msg is a Mail::Message now

my $subject = $msg->subject;         # The message's subject
my @cc      = $msg->cc;              # List of Mail::Address'es

my Mail::Message::Head $head = $msg->head;
my Mail::Message::Body $body = $msg->decoded;
$msg->decoded->print($outfile);

# Send a simple email
Mail::Message->build
  ( To             => 'you AT example.com'
  , From           => 'me AT example.com'
  , Subject        => "My subject"
  , data           => "Some plain text content"
  )->send(via => 'postfix');

my $reply_msg = Mail::Message->reply(...);
my $frwd_msg  = Mail::Message->forward(...);

📖 DESCRIPTION

A "Mail::Message" object is a container for MIME-encoded message information, as defined by RFC2822. Everything what is not specificaly related to storing the messages in mailboxes (folders) is implemented in this class. Methods which are related to folders is implemented in the Mail::Box::Message extension.

The main methods are get(), to get information from a message header field, and decoded() to get the intended content of a message. But there are many more which can assist your program.

Complex message handling, like construction of replies and forwards, are implemented in separate packages which are autoloaded into this class. This means you can simply use these methods as if they are part of this class. Those package add functionality to all kinds of message objects.

Extends "DESCRIPTION" in Mail::Reporter.

⚙️ METHODS

Extends "METHODS" in Mail::Reporter.

🏗️ Constructors

Extends "Constructors" in Mail::Reporter.

🛠️ Constructing a message

📦 The message

📋 The header

💪 The body

🏷️ Flags

📜 The whole message as text

🔧 Internals

⚠️ Error handling

Extends "Error handling" in Mail::Reporter.

🧹 Cleanup

Extends "Cleanup" in Mail::Reporter.

📚 DETAILS

🏗️ Structure of a Message

A MIME-compliant message is build upon two parts: the header and the body.

The header

The header is a list of fields, some spanning more than one line (folded) each telling something about the message. Information stored in here are for instance the sender of the message, the receivers of the message, when it was transported, how it was transported, etc. Headers can grow quite large.

In MailBox, each message object manages exactly one header object (a Mail::Message::Head) and one body object (a Mail::Message::Body). The header contains a list of header fields, which are represented by Mail::Message::Field objects.

The body

The body contains the "payload": the data to be transferred. The data can be encoded, only accessible with a specific application, and may use some weird character-set, like Vietnamese; the MailBox distribution tries to assist you with handling these e-mails without the need to know all the details. This additional information ("meta-information") about the body data is stored in the header. The header contains more information, for instance about the message transport and relations to other messages.

💻 Message object implementation

The general idea about the structure of a message is

Mail::Message
 |  |
 |  `-has-one--Mail::Message::Body
 |
 `----has-one--Mail::Message::Head
                 |
                 `-has-many--Mail::Message::Field

However: there are about 7 kinds of body objects, 3 kinds of headers and 3 kinds of fields. You will usually not see too much of these kinds, because they are merely created for performance reasons and can be used all the same, with the exception of the multipart bodies.

A multipart body is either a Mail::Message::Body::Multipart (mime type "multipart/*") or a Mail::Message::Body::Nested (mime type "message/rfc822"). These bodies are more complex:

Mail::Message::Body::Multipart
 |
 `-has-many--Mail::Message::Part
              |  |
              |  `-has-one--Mail::Message::Body
              |
              `----has-one--Mail::Message::Head

Before you try to reconstruct multiparts or nested messages yourself, you can better take a look at Mail::Message::Construct::Rebuild.

🧬 Message class implementation

The class structure of messages is very close to that of folders. For instance, a Mail::Box::File::Message relates to a Mail::Box::File folder.

As extra level of inheritance, it has a Mail::Message, which is a message without location. And there is a special case of message: Mail::Message::Part is a message encapsulated in a multipart body.

The message types are:

Mail::Box::Mbox::Message            Mail::Box::POP3::Message
|  Mail::Box::Dbx::Message      Mail::Box::IMAP4::Message  |
|  |                                                    |  |
Mail::Box::File::Message             Mail::Box::Net::Message
        |                                      |
        |       Mail::Box::Maildir::Message    |
        |       |   Mail::Box::MH::Message     |
        |       |   |                          |
        |       Mail::Box::Dir::Message        |
        |                |                     |
        `------------.   |   .-----------------'
                     |   |   |
                  Mail::Box::Message    Mail::Message::Part
                     |                     |
                     |       .-------------'
                     |       |
                 Mail::Message
                     |
                     |
               Mail::Reporter (general base class)

By far most folder features are implemented in Mail::Box, so available to all folder types. Sometimes, features which appear in only some of the folder types are simulated for folders that miss them, like sub-folder support for MBOX.

Two strange other message types are defined: the Mail::Message::Dummy, which fills holes in Mail::Box::Thread::Node lists, and a Mail::Box::Message::Destructed, this is an on purpose demolished message to reduce memory consumption.

🏷️ Labels

Labels (also named "Flags") are used to indicate some special condition on the message, primary targeted on organizational issues: which messages are already read or should be deleted. There is a very strong user relation to labels.

The main complication is that each folder type has its own way of storing labels. To give an indication: MBOX folders use "Status" and "X-Status" header fields, MH uses a ".mh-sequences" file, MAILDIR encodes the flags in the message's filename, and IMAP has flags as part of the protocol.

Besides, some folder types can store labels with user defined names, where other lack that feature. Some folders have case-insensitive labels, other don't. Read all about the specifics in the manual page of the message type you actually have.

Predefined labels

To standardize the folder types, MailBox has defined the following labels, which can be used with the label() and labels() methods on all kinds of messages:

Status and X-Status fields

Mbox folders have no special means of storing information about messages (except the message separator line), and therefore have to revert to adding fields to the message header when something special comes up. This feature is also enabled for POP3, although whether that works depends on the POP server.

All applications which can handle mbox folders support the "Status" and "X-Status" field conventions. The following encoding is used:

FlagFieldLabel
RStatusseen (Read)
OStatusold (not recent)
AX-Statusreplied (Answered)
FX-Statusflagged

There is no special flag for "deleted", which most other folders support: messages flagged to be deleted will never be written to a folder file when it is closed.

🔍 DIAGNOSTICS

📎 SEE ALSO

This module is part of Mail-Message distribution version 3.012, built on February 11, 2022. Website: http://perl.overmeer.net/CPAN/

📄 LICENSE

Copyrights 2001-2022 by Mark Overmeer (markov AT cpan.org). For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/

Mail::Message □✕
📛 NAME 🚀 Quick Reference 🔗 INHERITANCE 📝 SYNOPSIS 📖 DESCRIPTION ⚙️ METHODS
🏗️ Constructors 🛠️ Constructing a message 📦 The message 📋 The header 💪 The body 🏷️ Flags 📜 The whole message as text 🔧 Internals ⚠️ Error handling 🧹 Cleanup
📚 DETAILS
🏗️ Structure of a Message 💻 Message object implementation 🧬 Message class implementation 🏷️ Labels
🔍 DIAGNOSTICS 📎 SEE ALSO 📄 LICENSE

Generated by phpman v4.9.29 · Markdown · JSON · MCP Author: Che Dong Under GNU General Public License
2026-07-21 00:13 @2600:1f28:365:80b0:d8a5:c3c6:bf94:28c0
CrawledBy CCBot/2.0 (https://commoncrawl.org/faq/)
Valid XHTML 1.0 Transitional!Valid CSS!
Enhanced by LLM: deepseek-v4-flash / taotoken.net / www.chedong.com - original format

^_top_^