Mail::I...tructure(3)

💌 NAME 💌

Mail::IMAPClient::BodyStructure — bestie, it parses your fetched results ✨

This is the Mail::I...tructure(3) page, from the User Contributed Perl Documentation collection, and we are about to make sense of all of it, together 🫶

🌈 SYNOPSIS 🌈

use Mail::IMAPClient;
use Mail::IMAPClient::BodyStructure;

my $imap = Mail::IMAPClient->new(
    Server => $server, User => $login, Password => $pass
);

$imap->select("INBOX") or die "Could not select INBOX: $@\n";

my @recent = $imap->search("recent") or die "No recent msgs in INBOX\n";

foreach my $id (@recent) {
    my $bsdat = $imap->fetch( $id, "bodystructure" );
    my $bso   = Mail::IMAPClient::BodyStructure->new( join("", $imap->History) );
    my $mime  = $bso->bodytype . "/" . $bso->bodysubtype;
    my $parts = map( "\n\t" . $_, $bso->parts );
    print "Msg $id (Content-type: $mime) contains these parts:$parts\n";
}

🦋 DESCRIPTION 🦋

Okay so here's the vibe: this extension parses the result of an IMAP FETCH BODYSTRUCTURE command and turns it into a perl data structure. Iconic. It also hands you a bunch of helper methods so you can actually pull the info back out of that data structure without crying 💅

This module requires Parse::RecDescent. No cap, you need it.

---

👑 Class Methods 👑

The following class method is available:

🎀 new

This class method is the constructor method for instantiating new Mail::IMAPClient::BodyStructure objects. It accepts exactly one argument: a string containing a server response to a FETCH BODYSTRUCTURE directive. That's it. That's the whole input 🍓

The module Mail::IMAPClient provides the get_bodystructure convenience method to simplify use of this module when you're starting with just a message's sequence number or unique ID (UID). Very much a "let me handle that for you" moment 🫶

💜 Object Methods 💜

The following object methods are available:

⭐ bodytype

Requires no arguments. Returns the bodytype for the message whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

⭐ bodysubtype

Requires no arguments. Returns the bodysubtype for the message whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

⭐ bodyparms

Requires no arguments. Returns the bodyparms for the message whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

⭐ bodydisp

Requires no arguments. Returns the bodydisp for the message whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

⭐ bodyid

Requires no arguments. Returns the bodyid for the message whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

⭐ bodydesc

Requires no arguments. Returns the bodydesc for the message whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

⭐ bodyenc

Requires no arguments. Returns the bodyenc for the message whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

⭐ bodysize

Requires no arguments. Returns the bodysize for the message whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

⭐ bodylang

Requires no arguments. Returns the bodylang for the message whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

⭐ bodystructure

Requires no arguments. Returns the bodystructure for the message whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

⭐ envelopestruct

Requires no arguments. Returns a Mail::IMAPClient::BodyStructure::Envelope object for the message, from the calling Mail::IMAPClient::Bodystructure object. A whole little object, just for you 🧚

⭐ textlines

Requires no arguments. Returns the textlines for the message whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

---

🌸 Mail::IMAPClient::BodyStructure::Envelope 🌸

So the IMAP standard says output from the IMAP FETCH ENVELOPE command will be an RFC2060 envelope structure. It further says that output from the FETCH BODYSTRUCTURE command may also contain embedded envelope structures — like, if a message's subparts contain one or more included messages, that's where they'd be hiding 🙈

Objects belonging to Mail::IMAPClient::BodyStructure::Envelope are Perl representations of these envelope structures. Which is a fancy way of saying: the nested parenthetical lists of RFC2060, translated into a Perl datastructure. Slay 💅

Bestie, listen — all of the fields relate to the specific part to which they belong. So output from a FETCH nnnn ENVELOPE command (or, in Mail::IMAPClient, $imap->fetch($msgid,"ENVELOPE") or my $env = $imap->get_envelope($msgid)) is for the message, but fields from within a bodystructure relate to the message subpart, not the parent message. Do not mix these up, I am begging 😭

An envelope structure's Mail::IMAPClient::BodyStructure::Envelope representation is a hash of thingies that looks like this:

{
   subject   => "subject",
   inreplyto => "reference_message_id",
   from      => [ addressStruct1 ],
   messageid => "message_id",
   bcc       => [ addressStruct1, addressStruct2 ],
   date      => "Tue, 09 Jul 2002 14:15:53 -0400",
   replyto   => [ adressStruct1, addressStruct2 ],
   to        => [ adressStruct1, addressStruct2 ],
   sender    => [ adressStruct1 ],
   cc        => [ adressStruct1, addressStruct2 ],
}

The ...::Envelope object also has methods for accessing data in the structure. They are:

🦋 date

Returns the date of the message.

🦋 inreplyto

Returns the message id of the message to which this message is a reply.

🦋 subject

Returns the subject of the message.

🦋 messageid

Returns the message id of the message.

---

You can also use the following methods to get addressing information. Each of these methods returns an array of Mail::IMAPClient::BodyStructure::Address objects, which are perl data structures representing RFC2060 address structures 💖

Some of these arrays would naturally contain one element (such as from, which normally contains a single "From:" address); others will often contain more than one address. But because RFC2060 defines all of these as "lists of address structures", they are all translated into arrays of ...::Address objects. Rules are rules, periodt.

See the section on Mail::IMAPClient::BodyStructure::Address, below, for alternate (and preferred) ways of accessing these data 👀

The methods available are:

💌 bcc

Returns an array of blind cc'ed recipients' address structures. (Don't expect much in here unless the message was sent from the mailbox you're poking around in, by the way.)

💌 cc

Returns an array of cc'ed recipients' address structures.

💌 from

Returns an array of "From:" address structures — usually just one.

💌 replyto

Returns an array of "Reply-to:" address structures. Once again there is usually just one address in the list.

💌 sender

Returns an array of senders' address structures — usually just one, and usually the same as from.

💌 to

Returns an array of recipients' address structures.

---

Each of the methods that returns a list of address structures (i.e. a list of Mail::IMAPClient::BodyStructure::Address arrays) also has an analogous method that will return a list of E-Mail addresses instead. The addresses are in the format personalname <mailboxname@hostname> (see the section on Mail::IMAPClient::BodyStructure::Address, below). However, if the personal name is 'NIL' then it is omitted from the address. Gone. Not invited to the party 🎀

These methods are:

🌟 bcc_addresses

Returns a list (or an array reference if called in scalar context) of blind cc'ed recipients' email addresses. (Don't expect much in here unless the message was sent from the mailbox you're poking around in, by the way.)

🌟 cc_addresses

Returns a list of cc'ed recipients' email addresses. If called in a scalar context it returns a reference to an array of email addresses.

🌟 from_addresses

Returns a list of "From:" email addresses. If called in a scalar context it returns the first email address in the list. (It's usually a list of just one anyway.)

🌟 replyto_addresses

Returns a list of "Reply-to:" email addresses. If called in a scalar context it returns the first email address in the list.

🌟 sender_addresses

Returns a list of senders' email addresses. If called in a scalar context it returns the first email address in the list.

🌟 to_addresses

Returns a list of recipients' email addresses. If called in a scalar context it returns a reference to an array of email addresses.

Ngl, context affects the behavior of all of the above methods. Scalar context and list context are two completely different girlies here 💀

Those fields that will commonly contain multiple entries (i.e. they are recipients) will return an array reference when called in scalar context. You can use this behavior to optimize performance 🔥

Those fields that will commonly contain just one address (the sender's) will return the first (and usually only) address. You can use this behavior to optimize your development time. Which is the real flex, honestly 👑

💌 Addresses and the Mail::IMAPClient::BodyStructure::Address 💌

Okay so bestie, several components of an envelope structure are literally address structures. Mail::IMAPClient parses each one into its very own object, Mail::IMAPClient::BodyStructure::Address, and it looks like this:

{
   mailboxname  => 'somebody.special',
   hostname     => 'somplace.weird.com'
   personalname => 'Somebody Special
   sourceroute  => 'NIL'
}

Yes, copy that exactly — quirks, missing bits, and all. 🫶

RFC2060 says that each address component of a bodystructure is a list of address structures, so Mail::IMAPClient::BodyStructure parses each of these into an array of Mail::IMAPClient::BodyStructure::Address objects. It’s giving “one address, but make it a whole array” energy. ✨

Each of these objects has the following methods available to it:

• mailboxname — returns the "mailboxname" portion of the address, which is the part to the left of the '@' sign.
• hostname — returns the "hostname" portion of the address, which is the part to the right of the '@' sign.
• personalname — returns the "personalname" portion of the address, which is the part of the address that’s treated like a comment.
• sourceroute — returns the "sourceroute" portion of the address, which is typically "NIL".

Taken together, the parts of an address structure form an address that will look something like this:

"personalname <mailboxname@hostname>"

And here’s the little note, because this is important: because the Mail::IMAPClient::BodyStructure::Address objects come in arrays, it’s generally easier to use the methods available to Mail::IMAPClient::BodyStructure::Envelope to obtain all of the addresses in a particular array in one operation. These methods are provided, however, in case you’d rather do things the hard way. (And also because the aforementioned methods from Mail::IMAPClient::BodyStructure::Envelope need them anyway.) No cap — sometimes the “hard way” is just the supporting-character way. 💅

---

✍️ AUTHOR ✍️

Original author: David J. Kernen; Reworked by: Mark Overmeer; Maintained by Phil Pearl.

---

👀 SEE ALSO 👀

perl(1), Mail::IMAPClient, Parse::RecDescent, and RFC2060.

---

xoxo, your Unix bestie 🎀 — this Mail::I...tructure(3) page comes from perl v5.40.2, dated 2024-10-16. 💖