Sympa::Message(3Sympa)

📦
version 6.2.80 · 14 versions
, in fedora 43, fedora 44

💌 NAME 💌

Sympa::Message — mail message embedding for internal use in Sympa 🫶

(you're reading the Sympa::Message(3Sympa) page, straight out of the sympa 6.2.80 manual, bestie ✨)

🌸 SYNOPSIS 🌸

use Sympa::Message;
my $message = Sympa::Message->new($serialized, context => $list);

🦋 DESCRIPTION 🦋

Okay so picture this: while Sympa is processing a message, it has to link extra info to that message, rewrite headers, all of that. And back in the day that was lowkey a whole situation 😭 because if the message was signed, touching anything in the body would change its MD5 footprint. And then the message would probably get rejected by the clients that verify its identity — which is, honestly, kind of a good thing, since that's literally the entire reason people use MD5 in the first place. So with messages like that, the process was complex. The fix? Sympa decided to embed any message it handles in a "Message" object, and boom — process made easier. slay 💅

🔮 Methods and functions 🔮

⭐ new ( $serialized, context => $that, KEY => value, ... )

Constructor. Creates a brand new Sympa::Message object. ✨

Parameters:

  • $serialized — Serialized message.
  • context => object — Context. A Sympa::List object, a Robot or '*'.
  • key => value, ... — Metadata.

Returns:

  • A new Sympa::Message object, or undef, if something went wrong. 😭

💖 dup ( )

Copy constructor. Gets a deep copy of the instance. two of them. twins. iconic.

🎀 to_string ( [ original => 0|1 ] )

Serializer. Returns serialized data of the Message object.

Parameter:

  • original => 0|1 — If set to 1 and content has been decrypted, returns original content. Default is 0.

Returns:

  • Serialized representation of the Message object.

🌈 add_header ( $field, $value, [ $index ] )

Instance method. Adds a header field named $field with body $value. If $index is given, the field gets inserted at the place it indicates: if it is 0, the field will be prepended. front of the line energy.

💅 delete_header ( $field, [ $index ] )

Instance method. Deletes all occurrences of the header field named $field. gone. bye.

🦋 replace_header ( $field, $value, [ $index ] )

Instance method. Replaces header fields named $field with $value.

Instance method. Gets the header of the message as a MIME::Head instance.

Heads up bestie ⚠️ the returned value is a real reference to internal data structure. Even if you changed it, the string representation of the message may not be updated. Instead, use "add_header"(), "delete_header"() or "replace_header"() to modify the header. iykyk.

🔥 check_spam_status ( )

Instance method. Gets the spam status according to the spam_status scenario and sets it as the {spam_status} attribute.

🌟 aggregate_authentication_results ( )

Instance method. TBD. (yes, that's literally what it says 💀)

🧚 dkim_sign ( dkim_d => $d, [ dkim_i => $i ], dkim_selector => $selector, dkim_privatekey => $privatekey )

Instance method. Adds a DKIM signature to the message. 🔏

💜 check_dkim_signature ( )

Deprecated on Sympa 6.2.71b. Use check_dkim_sigs().

🍓 check_dkim_sigs ( )

Instance method. Checks the DKIM signature of the message and sets or clears the {dkim_pass} item of the message object.

Returns:

  • An array of the overall result of checking and authentication result(s).

🌈 remove_invalid_dkim_signature ( )

Deprecated on Sympa 6.2.74.

Instance method. Verifies DKIM signatures included in the message, and if any of them are invalid, removes them.

💫 check_arc_chain ( )

Deprecated on Sympa 6.2.71b. Use check_arc_seals().

🎀 check_arc_seals ( )

Instance method. Checks the chain of ARC seals in the message.

Returns:

  • An array of the result of checking and authentication result.

Note:

  • Use of aggregate_authentication_results() is recommended instead of using this method derectly. (their spelling, not mine 🙈)

🦋 arc_seal ( )

Instance method. Adds a new ARC seal if there's an {arc_cv} from check_arc_seals() and the cv is none or valid.

Returns true value if the seal was successfully added. 🎉

✨ as_entity ( )

Instance method. Gets message content as a MIME entity (MIME::Entity instance).

Note that the returned value is a real reference to internal data structure. Even if it was changed, the string representation of the message may not be updated. Below is the better way to modify a message. 👇
my $entity = $message->as_entity->dup;
# ... Modify $entity...
$message->set_entity($entity);

💖 set_entity ( $entity )

Instance method. Updates the message with a MIME entity (MIME::Entity instance). String representation will be automatically updated. no extra steps, we love that.

🌸 as_string ( )

Instance method. Gets a string representation of the message.

Parameter:

  • original => 0|1 — If set to 1 and content has been decrypted, returns original content. Default is 0.
Note that a method like "set_string()" does not exist: you would be better off creating a new instance rather than replacing the entire content. fr fr.

⭐ body_as_string ( )

Instance method. Gets the body of the message as string.

Note that the result won't be decoded.

🎀 header_as_string ( )

Instance method. Gets the header part of the message as string.

Note that the result won't be decoded nor unfolded.

🧚 get_header ( $field, [ $sep ] )

Instance method. Gets value(s) of the header field $field, stripping the trailing newline.

In scalar context without $sep, returns the first occurrence or "undef". If $sep is defined, returns all occurrences joined by it, or "undef". Otherwise, in array context, returns an array of all occurrences or "()".

Note: Folding newlines will not be removed. 🙈

💅 get_decoded_header ( $tag, [ $sep ] )

Instance method. Returns the header value decoded to UTF-8, or undef. The trailing newline will be removed. If $sep is given, returns all occurrences joined by it.

🍓 dump ( $output )

Instance method. Dumps a Message object to a stream.

Parameters:

  • $output — the stream to which dump the object.

Returns:

  1. if everything's alright 🎉

💫 add_topic ( $output )

Note: No longer used.

Instance method. Adds a topic and puts the header X-Sympa-Topic.

Parameters:

  • $output — the string containing the topic to add.

Returns:

  1. if everything's alright 🎉

🌈 get_topic ( )

Note: No longer used.

Instance method. Gets the topic of the message.

Parameters:

  • None.

Returns:

  • the topic — if it exists
  • empty string — otherwise

🧚 clean_html ( )

Instance method. Encodes HTML parts of the message by UTF-8 and strips scripts included in them. 🧼✨

👑 smime_decrypt ( )

Instance method. Decrypts the message using the private key of the user.

Note that this method modifies the Message object.

Parameters:

  • None.

Returns:

  • True value if the message was decrypted. Otherwise false value.
  • If decrypting succeeded, the {smime_crypted} item is set.

🔥 smime_encrypt ( $email )

Instance method. Encrypts the message using the certificate of the user.

Note that this method modifies the Message object.

Parameters:

  • $email — E-mail address of the user.

Returns:

  • True value if encryption succeeded, or "undef".

⭐ smime_sign ( )

Instance method. Adds an S/MIME signature to the message.

Signing key is taken from what's stored in the list directory. 🗝️

Parameters:

  • None.

Returns:

  • True value if the message was successfully signed. Otherwise false value.

🦋 check_smime_signature ( )

Instance method. Verifies the S/MIME signature of the message, and if verification succeeded, sets the {smime_signed} item to true.

Parameters:

  • None

Returns:

  • 1 if the signature is successfully verified. 0 otherwise. "undef" if something went wrong. 😭

💜 is_signed ( )

Instance method. Checks if the message is signed.

Note: This checks if the message has the appropriate content type and header parameters. Use check_smime_signature() to check if the message has properly signed content. ⚠️

Currently, S/MIME-signed messages with content type "multipart/signed" or "application/pkcs7-mime" (with smime-type="signed-data" parameter) are recognized. Enveloped-only messages are not supported. The other signature mechanisms such as PGP/MIME have not been supported yet.

Parameters:

  • None.

Returns:

  • 1 if the message is considered signed. 0 otherwise.

🎀 personalize ( $list, [ $rcpt ] )

Instance method. Personalizes a message with custom attributes of a user. ✨

Parameters:

  • $list — List object.
  • $rcpt — Recipient.
  • $data — Hashref. Additional data to be interpolated into the personalized message.

Returns:

  • The modified message itself, or "undef" if an error occurred. 😭

🌟 test_personalize ( $list )

DEPRECATED by Sympa 6.2.13. No longer available.

Instance method. Tests if personalization can be performed successfully over all subscribers of the list.

Parameters:

Returns:

  • 1 if it succeeded, or "undef".

💖 personalize_text ( $body, $list, [ $rcpt ], [ $data ] )

Function. Retrieves the customized data of the users, then parses the text. It returns the personalized text.

Parameters:

  • $body — Message body with the TT2.
  • $list — List object.
  • $rcpt — The recipient email.
  • $data — Hashref. Additional data to be interpolated into the personalized message.

Returns:

  • Customized text, or "undef" if an error occurred. 💀

🦋 prepare_message_according_to_mode ( $mode, $list )

Instance method. Transforms the message according to the reception mode: 'mail', 'notice' or 'txt'.

Note: 'html' mode was deprecated as of 6.2.23b.2.

By 'nomail', 'digest', 'digestplain' or 'summary' mode, the message is not modified.

Returns the modified message object itself, or "undef" if the transformation failed.

🎀 decorate ($list, [ mode => personalization mode ] )

Instance method. Adds a footer/header to a message. 💅

🔥 reformat_utf8_message ( )

Instance method. Reformats bodies of text parts contained in the message using the recommended encoding schema and/or charsets defined by MIME::Charset.

MIME-compliant headers are appended / modified. And a custom X-Mailer: header is appended :). 🥰

Parameters:

  • $attachments — ref(ARRAY) - messages to be attached as subparts.

Returns:

  • string

🎀 shelve_personalization ( type => $type )

Instance method, bestie. It shelves personalization (aka the "merge feature") if it needs to. $type is either 'web' or 'mail'.

🚨 Heads up: this one dies if the context of the message was not List. Not a vibe. Just gone. 💀

🌸 get_plain_body ( )

Instance method. Gets you the decoded content of the text/plain part.

The text gets converted to UTF-8, and flowed text (see RFC 3676) gets conjuncted. Periodt. ✨

💅 check_virus_infection ( [ debug => 1 ] )

Instance method. Checks the message using the anti-virus plugin — but only if the configuration requests it. No config, no check, no drama.

Parameters:

  • TBD. (yes, it literally says TBD, we don't make the rules 🫠)

Returns:

  • The name of malware the message contains, if any;
  • "unknown" for unidentified malware;
  • "undef" if checking failed;
  • otherwise 0.

🦋 get_plaindigest_body ( )

Instance method. Returns a plain text version of the message, suitable for use in plain text digests. Here's the tea, point by point:

  • Most attachments are stripped out and replaced with a note that they've been stripped. text/plain parts are retained.
  • An attempt to convert text/html parts to plain text is made if there is no text/plain alternative.
  • All messages are converted from their original character set to UTF-8.
  • Parts of type message/rfc822 are recursed through in the same way, with brief headers included.
  • Any line consisting only of 30 hyphens has the first character changed to space (see RFC 1153). Lines are wrapped at 76 columns.

Parameters:

None.

Returns:

String.

👑 dmarc_protect ( )

Instance method. Munges the "From:" header field if we are using DMARC Protection mode. Munges!! okay!!

Parameters:

None.

Returns:

None. But lowkey important: the "From:" field of the message may be modified. 🙈

🍓 compute_topic ( )

Instance method. Computes the topic of the message. The topic is got from keywords defined in list parameter msg_topic.keywords. The keyword is applied on the subject and/or the body of the message according to list parameter msg_topic_keywords_apply_on.

Parameters:

None.

Returns:

String of tag(s), can be separated by ',', can be empty. So like, might be nothing. It's giving "we'll see". ✨

🧚 get_id ( )

Instance method. Gets the unique identifier of the instance.

Short, sweet, iconic. No notes. 💖

🌈 Context and Metadata 🌈

The context and metadata you hand to the constructor are accessible as hash elements of the object. These are the ones everybody actually uses:

{context}

Context of the message, Sympa::List object, robot or '*'.

{date}

The UNIX time messages was initially accepted, or the time message should be delivered.

{domainpart} {listname} {listtype} {localpart}

Domain, name, type and local part of context.

{priority}

Priority of the message. Prioritizing!! 💅

{tag}

Tag of packet used by bulk spool to control logging. '0' is the first message of multiple packet. 'z' is the last. 's' is the single message with single packet.

{time}

The Unix time in floating point number when the message was stored into the spool. This is used by bulk spool.

💖 Attributes 💖

These are accessible as hash elements of objects.

{checksum}

No longer used. It is kept for compatibility with Sympa 6.1.x or earlier. See also sympa upgrade incoming command line. (Retro vibes only, don't touch. ✋)

{envelope_sender}

Envelope sender, a.k.a. "Unix From". This is not always same as {sender} attribute nor the content of "From:" field.

'<>' will be used for "null envelope sender".

{family}

Name of family (see Sympa::Family) the message corresponds to. This is given by familyqueue(8) program.

{gecos}

Display name of actual sender (see {sender} below), if any.

{md5_check}

True value indicates that the message has been authenticated by "md5" level (password authentication). This is set by web mailer of WWSympa and used by incoming spool.

{message_id}

Original message ID of the message.

{rcpt}

Recipients for delivery. This is kept for compatibility with earlier releases.

{sender}

Actual sender of the message. This is determined according to "sender_headers" configuration parameter. See also {envelope_sender} above.

{shelved}

Shelved processing. Hashref with multiple items. Currently these items are available:

  • arc_cv => "pass"|"fail"|"none" — Result of checking the chain of ARC seals. This is used to generate a new ARC seal, if ARC feature is enabled.
  • decorate => 1 — Adding footer/header if any.

This item was added on Sympa 6.2.59b.2 to avoid processing decoration twice with the messages stored into outgoing spool by earlier version of Sympa.

  • dkim_sign => 1 — Adding DKIM signature.
  • dmarc_protect => 1 — DMARC protection. See also "dmarc_protect"().
  • merge => "footer"|"all" — Personalizing.

On Sympa 6.2.58 or earlier, there was no distinction between "footer" and "all". The "merge" item in the messages stored into outgoing spool by earlier version of Sympa will be treated as "all".

  • smime_encrypt => 1 — Adding S/MIME encryption.
  • smime_sign => 1 — Adding S/MIME signature.
  • tracking => "dsn"|"mdn"|"r"|"w"|"verp" — Requesting tracking feature including VERP.

This is used by bulk spool.

{spam_status}

Result of spam check. This is set by "check_spam_status"() method.

🫧 Serialization 🫧

A Sympa::Message object includes number of slots as hash items: metadata, context, attributes and message content. Metadata including context are given by spool: See "Marshaling and unmarshaling metadata" in Sympa::Spool.

Logically, objects are stored into physical spool as serialized form and deserialized when they are fetched from spool. Attributes will be serialized and deserialized along with raw message content. Attributes are encoded in "X-Sympa-*:" pseudo-header fields and "Return-Path:" header field. Below is an example of serialized form. Look at her. Gorgeous. ✨

X-Sympa-Message-ID: 123456789.12345@domain.name : {message_id} attribute
X-Sympa-Sender: user01@user.sympa.test          : {sender} attribute
X-Sympa-Display-Name: Infant                    : {gecos} attribute
X-Sympa-Shelved: dkim_sign; tracking=mdn        : {shelved} attribute
X-Sympa-Spam-Status: ham                        : {spam_status} attribute
Return-Path: sympa-request@domain.name          : {envelope_sender} attribute
Message-Id: <123456789.12345@domain.name>       :   ---
From: Infant <user@other.host.dom>              :    |
To: User <user@some.host.name>                  :    |
Subject: Howdy world                            :    | Raw message content
X-Sympa-Topic: sometopic                        :    |
                                                :    |
Bonjour, le monde.                              :    |
                                                :   ---

On msg, automatic and bounce spools, "Return-Path:" header fields are given by MDA and "X-Sympa-*:" header fields are given by queue programs. On other spools, they are given by components of Sympa.

Pseudo-header fields should appear at beginning of serialized content. Fields appear at other places (e.g. "X-Sympa-Topic:" field above) are not attributes but are the part of raw message content.

Pseudo-header fields should not be included in actually sent messages. Do not. 🚫

⚠️ CAVEAT ⚠️

Adding "Return-Path:" field

We trust in "Return-Path:" header field only at the top of message to prevent forgery. To ensure it will be added to messages by MDA:

  • Sendmail — Add "P" in the "F=" flags of local mailer line (such as "Mlocal").
  • Postfix
    • local(8) — Prepending "Return-Path:" is available by default.
    • pipe(8) — Add "R" to the "flags=" attributes in master.cf.

Additionally with Postfix 2.3 or later, add an empty "null_sender=" attribute. Or "null envelope sender" would be replaced with "<MAILER-DAEMON>".

  • Exim — Set "return_path_add" to be true with pipe_transport.
  • qmail — Use preline(1).
  • sympa-milter — As of version 0.7, prepending "Return-Path:" is available.

Configure your MDA correctly, bestie. This is not the part to freestyle. 🙏

🐛 BUGS 🐛

get_plaindigest_body() seems to ignore any text after a UUencoded attachment.

Yeah. She just stops reading. It's giving "known issue" energy. 😭

📜 HISTORY 📜

Message module appeared on Sympa 3.3.6. It was initially written by:

  • Serge Aumont <sa AT cru.fr>
  • Olivier Salaün <os AT cru.fr>

get_plaindigest_body, ex. "plain_body_as_string" in PlainDigest, was initially written by Chris Hastie. It appeared on Sympa 4.2b.1.

(c) Chris Hastie 2004 - 2008.

Renamed and merged Sympa::Message appeared on Sympa 6.2.

Okay we did it, that's the whole page, no crumbs left 💅✨ — this was version 6.2.80, dated 2026-10-19, and yeah, it's the Sympa::Message(3Sympa) man page. Go forth and never forge a Return-Path: header, mwah 🫶💖

📦 where this page comes from