Message(3)

💌 Message(3) — the whole vibe

okay bestie, welcome to the Cyrus::Annotator::Message era ✨ this is a page from the User Contributed Perl Documentation section of the manual (yes, the manual name is literally right there in the title, we're folding it in like a cute little name tag 🎀).

---

🌸 NAME 🌸

Cyrus::Annotator::Message — it's the whole representation of a message that's about to get annotated. like, the message in its little outfit before the annotator daemon does its thing 💅

---

✨ SYNOPSIS ✨

the moment you've been waiting for, the group chat receipts:

  use warnings;
  use strict;
  package MyAnnotatorDaemon;
  use base Cyrus::Annotator::Daemon;

  sub annotate_message
  {
      my ($message) = @_;

      $message->set_flag('\Flagged');
      $message->set_shared_annotation('/comment', 'Hello!!');
  }

  MyAnnotatorDaemon->run();

see how easy that was?? iconic behaviour fr fr 👑

---

🦋 DESCRIPTION 🦋

this module encapsulates a message which is being processed by the annotator daemon. that's it, that's the job. it's giving "message wrangler, but make it a Perl object" 💖

---

💅 METHODS 💅

Cyrus::Annotator::Message has the following methods. yes, all of them. we're listing every single one, no skips 🫶

new(%args)

the constructor, the origin story, the main character entrance 🌟 it takes the following args:

 # required
 * BODYSTRUCTURE => parsed bodystructure

 # optional (but you need to provide SOMETHING if your code uses any
 # of the accessors)
 * GUID => 40 character sha1
 * HEADER => Mail::Header object with headers pre-parsed
 * FILENAME => path to rfc822 file

 # totally optional (will be considered empty if not set)
 * FLAGS => array of already set flags
 * ANNOTATIONS => array of already set annotations

ok so real talk — BODYSTRUCTURE is required, no negotiating. the rest? optional, but if you skip the optional ones and then call the accessors that need them, that's on you bestie 😭

---

fh()

returns a read-only filehandle to the raw (rfc822) representation of the full message. read-only, so don't even think about writing to it 💀

---

decode_part($Part, $Content)

given some content, decode it from the part's content encoding and charset. it's the translator of the operation 🌈

---

read_part_content($Part, $nbytes)

returns the first n bytes of the bodypart passed. this is a section of the bodystructure (hashref). if no part is passed, it's the raw message.

if no 'nbytes' is passed, read the entire part. the whole thing. no crumbs left 🍓

---

header()

returns a Mail::Header object containing all the headers of the message. all of them. every last one ✨

---

bodystructure()

returns a structure.

is a structure closely based on the IMAP BODYSTRUCTURE, decoded into a hash, including recursively all MIME sections. in general, the following items are defined for all body structures:

• MIME-Type
• MIME-Subtype
• Content-Type
• Content-Description
• Content-Disposition
• Content-Language

body structures which have a MIME-Type of 'multipart' contain the following items:

• MIME-Subparts

for body structures except those that have a MIME-Type of 'multipart', the following are defined:

• Content-ID
• Content-Description
• Content-Transfer-Encoding
• Content-MD5
• Size
• Lines
• Offset
• HeaderSize

so basically: multipart ones get MIME-Subparts, non-multipart ones get that whole second list. lowkey a lot of fields but we love a thorough queen 👑

---

guid()

returns the hex encoded (40 character) sha1 of the rfc822 representation. 40 characters. count them. slay 💜

---

has_flag($name) / set_flag($name) / clear_flag($name)

check for the boolean value of a flag with $name, set the flag and remove the flag respectively.

⚠️ note that changes are not immediate. they will be applied by the annotator at the end. so like, patience bestie, the daemon handles it 🧚

for example:

  $message->set_flag("\\Flagged");

---

get_shared_annotation($entry) / get_private_annotation($entry) / set_shared_annotation($entry, $value) / set_private_annotation($entry, $value) / clear_shared_annotation($entry) / clear_private_annotation($entry)

get, set and clear the value of an annotation, either shared or private. the "get" accessors return a string with the value. clear is the same as set with $value of the empty string ('').

for example:

  $message->set_shared_annotation('/comment', 'Hello World');

shared or private, you got options, and honestly? both are valid 💖

---

get_changed()

returns two arrayrefs — [['flagname', 'bool']] and [['entry', 'type', 'value']], e.g.

  [["\\Flagged", 1]], [['/comment', 'value.shared', 'Hello World']]

the receipts of everything that changed. periodt 📋✨

---

🔥 SEE ALSO 🔥

RFC3501, RFC5257. go read them, they're the lore iykyk 📚

---

👑 AUTHOR 👑

Greg Banks <gnb@fastmail.fm>. Bron Gondwana <brong@fastmail.fm>. legends, honestly 🙌

---

and that's the whole page bestie!! perl v5.42.3, dated 2026-09-11, filed under Message(3) — mwah, go annotate something gorgeous 💋💖