.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Sympa::Message 3Sympa"
.TH Sympa::Message 3Sympa "2022-11-25" "6.2.70" "sympa 6.2.70"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sympa::Message \- Mail message embedding for internal use in Sympa
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Sympa::Message;
\&  my $message = Sympa::Message\->new($serialized, context => $list);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
While processing a message in Sympa, we need to link information to the
message, modify headers and such.  This was quite a problem when a message was
signed, as modifying anything in the message body would alter its \s-1MD5\s0
footprint. And probably make the message to be rejected by clients verifying
its identity (which is somehow a good thing as it is the reason why people use
\&\s-1MD5\s0 after all). With such messages, the process was complex. We then decided
to embed any message treated in a \*(L"Message\*(R" object, thus making the process
easier.
.SS "Methods and functions"
.IX Subsection "Methods and functions"
.ie n .IP "new ( $serialized, context => $that, \s-1KEY\s0 => value, ... )" 4
.el .IP "new ( \f(CW$serialized\fR, context => \f(CW$that\fR, \s-1KEY\s0 => value, ... )" 4
.IX Item "new ( $serialized, context => $that, KEY => value, ... )"
\&\fIConstructor\fR.
Creates a new Sympa::Message object.
.Sp
Parameters:
.RS 4
.ie n .IP "$serialized" 4
.el .IP "\f(CW$serialized\fR" 4
.IX Item "$serialized"
Serialized message.
.IP "context => object" 4
.IX Item "context => object"
Context.  Sympa::List object, Robot or \f(CW\*(Aq*\*(Aq\fR.
.IP "key => value, ..." 4
.IX Item "key => value, ..."
Metadata.
.RE
.RS 4
.Sp
Returns:
.Sp
A new Sympa::Message object, or \fIundef\fR, if something went wrong.
.RE
.IP "dup ( )" 4
.IX Item "dup ( )"
\&\fICopy constructor\fR.
Gets deep copy of instance.
.IP "to_string ( [ original => 0|1 ] )" 4
.IX Item "to_string ( [ original => 0|1 ] )"
\&\fISerializer\fR.
Returns serialized data of Message object.
.Sp
Parameter:
.RS 4
.IP "original => 0|1" 4
.IX Item "original => 0|1"
If set to 1 and content has been decrypted, returns original content.
Default is 0.
.RE
.RS 4
.Sp
Returns:
.Sp
Serialized representation of Message object.
.RE
.ie n .IP "add_header ( $field, $value, [ $index ] )" 4
.el .IP "add_header ( \f(CW$field\fR, \f(CW$value\fR, [ \f(CW$index\fR ] )" 4
.IX Item "add_header ( $field, $value, [ $index ] )"
\&\fIInstance method\fR.
Adds a header field named \f(CW$field\fR with body \f(CW$value\fR.
If \f(CW$index\fR is given, the field will be inserted at the place it indicates:
If it is \f(CW0\fR, the field will be prepended.
.ie n .IP "delete_header ( $field, [ $index ] )" 4
.el .IP "delete_header ( \f(CW$field\fR, [ \f(CW$index\fR ] )" 4
.IX Item "delete_header ( $field, [ $index ] )"
\&\fIInstance method\fR.
Deletes all occurrences of the header field named \f(CW$field\fR.
.ie n .IP "replace_header ( $field, $value, [ $index ] )" 4
.el .IP "replace_header ( \f(CW$field\fR, \f(CW$value\fR, [ \f(CW$index\fR ] )" 4
.IX Item "replace_header ( $field, $value, [ $index ] )"
\&\fIInstance method\fR.
Replaces header fields named \f(CW$field\fR with \f(CW$value\fR.
.IP "head" 4
.IX Item "head"
\&\fIInstance method\fR.
Gets header of the message as MIME::Head instance.
.Sp
Note that returned value is real reference to internal data structure.
Even if it was changed, string representation of message may not be updated.
Alternatively, use \*(L"add_header\*(R"(), \*(L"delete_header\*(R"() or
\&\*(L"replace_header\*(R"() to modify header.
.IP "check_spam_status ( )" 4
.IX Item "check_spam_status ( )"
\&\fIInstance method\fR.
Gets spam status according to spam_status scenario
and sets it as {spam_status} attribute.
.ie n .IP "dkim_sign ( dkim_d => $d, [ dkim_i => $i ], dkim_selector => $selector, dkim_privatekey => $privatekey )" 4
.el .IP "dkim_sign ( dkim_d => \f(CW$d\fR, [ dkim_i => \f(CW$i\fR ], dkim_selector => \f(CW$selector\fR, dkim_privatekey => \f(CW$privatekey\fR )" 4
.IX Item "dkim_sign ( dkim_d => $d, [ dkim_i => $i ], dkim_selector => $selector, dkim_privatekey => $privatekey )"
\&\fIInstance method\fR.
Adds \s-1DKIM\s0 signature to the message.
.IP "check_dkim_signature ( )" 4
.IX Item "check_dkim_signature ( )"
\&\fIInstance method\fR.
Checks \s-1DKIM\s0 signature of the message
and sets or clears {dkim_pass} item of the message object.
.IP "remove_invalid_dkim_signature ( )" 4
.IX Item "remove_invalid_dkim_signature ( )"
\&\fIInstance method\fR.
Verifies \s-1DKIM\s0 signatures included in the message,
and if any of them are invalid, removes them.
.IP "check_arc_chain ( )" 4
.IX Item "check_arc_chain ( )"
\&\fIInstance method\fR.
Checks \s-1ARC\s0 chain of the message
and sets {shelved}{arc_cv} item of the message object.
.IP "arc_seal ( )" 4
.IX Item "arc_seal ( )"
\&\fIInstance method\fR.
Adds a new \s-1ARC\s0 seal if there's an arc_cv from check_arc_chain and
the cv is none or valid.
.IP "as_entity ( )" 4
.IX Item "as_entity ( )"
\&\fIInstance method\fR.
Gets message content as \s-1MIME\s0 entity (MIME::Entity instance).
.Sp
Note that returned value is real reference to internal data structure.
Even if it was changed, string representation of message may not be updated.
Below is better way to modify message.
.Sp
.Vb 3
\&    my $entity = $message\->as_entity\->dup;
\&    # ... Modify $entity...
\&    $message\->set_entity($entity);
.Ve
.ie n .IP "set_entity ( $entity )" 4
.el .IP "set_entity ( \f(CW$entity\fR )" 4
.IX Item "set_entity ( $entity )"
\&\fIInstance method\fR.
Updates message with \s-1MIME\s0 entity (MIME::Entity instance).
String representation will be automatically updated.
.IP "as_string ( )" 4
.IX Item "as_string ( )"
\&\fIInstance method\fR.
Gets a string representation of message.
.Sp
Parameter:
.RS 4
.IP "original => 0|1" 4
.IX Item "original => 0|1"
If set to 1 and content has been decrypted, returns original content.
Default is 0.
.RE
.RS 4
.Sp
Note that method like \*(L"\fBset_string()\fR\*(R" does not exist:
You would be better to create new instance rather than replacing entire
content.
.RE
.IP "body_as_string ( )" 4
.IX Item "body_as_string ( )"
\&\fIInstance method\fR.
Gets body of the message as string.
.Sp
Note that the result won't be decoded.
.IP "header_as_string ( )" 4
.IX Item "header_as_string ( )"
\&\fIInstance method\fR.
Gets header part of the message as string.
.Sp
Note that the result won't be decoded nor unfolded.
.ie n .IP "get_header ( $field, [ $sep ] )" 4
.el .IP "get_header ( \f(CW$field\fR, [ \f(CW$sep\fR ] )" 4
.IX Item "get_header ( $field, [ $sep ] )"
\&\fIInstance method\fR.
Gets value(s) of header field \f(CW$field\fR, stripping trailing newline.
.Sp
\&\fBIn scalar context\fR without \f(CW$sep\fR, returns first occurrence or \f(CW\*(C`undef\*(C'\fR.
If \f(CW$sep\fR is defined, returns all occurrences joined by it, or \f(CW\*(C`undef\*(C'\fR.
Otherwise \fBin array context\fR, returns an array of all occurrences or \f(CW\*(C`()\*(C'\fR.
.Sp
Note:
Folding newlines will not be removed.
.ie n .IP "get_decoded_header ( $tag, [ $sep ] )" 4
.el .IP "get_decoded_header ( \f(CW$tag\fR, [ \f(CW$sep\fR ] )" 4
.IX Item "get_decoded_header ( $tag, [ $sep ] )"
\&\fIInstance method\fR.
Returns header value decoded to \s-1UTF\-8\s0 or undef.
Trailing newline will be removed.
If \f(CW$sep\fR is given, returns all occurrences joined by it.
.ie n .IP "dump ( $output )" 4
.el .IP "dump ( \f(CW$output\fR )" 4
.IX Item "dump ( $output )"
\&\fIInstance method\fR.
Dumps a Message object to a stream.
.Sp
Parameters:
.RS 4
.ie n .IP "$output" 4
.el .IP "\f(CW$output\fR" 4
.IX Item "$output"
the stream to which dump the object
.RE
.RS 4
.Sp
Returns:
.IP "1." 4
if everything's alright
.RE
.RS 4
.RE
.ie n .IP "add_topic ( $output )" 4
.el .IP "add_topic ( \f(CW$output\fR )" 4
.IX Item "add_topic ( $output )"
Note:
No longer used.
.Sp
\&\fIInstance method\fR.
Adds topic and puts header X\-Sympa-Topic.
.Sp
Parameters:
.RS 4
.ie n .IP "$output" 4
.el .IP "\f(CW$output\fR" 4
.IX Item "$output"
the string containing the topic to add
.RE
.RS 4
.Sp
Returns:
.IP "1." 4
if everything's alright
.RE
.RS 4
.RE
.IP "get_topic ( )" 4
.IX Item "get_topic ( )"
Note:
No longer used.
.Sp
\&\fIInstance method\fR.
Gets topic of message.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.RS 4
.IP "the topic" 4
.IX Item "the topic"
if it exists
.IP "empty string" 4
.IX Item "empty string"
otherwise
.RE
.RS 4
.RE
.IP "clean_html ( )" 4
.IX Item "clean_html ( )"
\&\fIInstance method\fR.
Encodes \s-1HTML\s0 parts of the message by \s-1UTF\-8\s0 and strips scripts included in
them.
.IP "smime_decrypt ( )" 4
.IX Item "smime_decrypt ( )"
\&\fIInstance method\fR.
Decrypts message using private key of user.
.Sp
Note that this method modifies Message object.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
True value if message was decrypted.  Otherwise false value.
.Sp
If decrypting succeeded, {smime_crypted} item is set.
.ie n .IP "smime_encrypt ( $email )" 4
.el .IP "smime_encrypt ( \f(CW$email\fR )" 4
.IX Item "smime_encrypt ( $email )"
\&\fIInstance method\fR.
Encrypts message using certificate of user.
.Sp
Note that this method modifies Message object.
.Sp
Parameters:
.RS 4
.ie n .IP "$email" 4
.el .IP "\f(CW$email\fR" 4
.IX Item "$email"
E\-mail address of user.
.RE
.RS 4
.Sp
Returns:
.Sp
True value if encryption succeeded, or \f(CW\*(C`undef\*(C'\fR.
.RE
.IP "smime_sign ( )" 4
.IX Item "smime_sign ( )"
\&\fIInstance method\fR.
Adds S/MIME signature to the message.
.Sp
Signing key is taken from what stored in list directory.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
True value if message was successfully signed.
Otherwise false value.
.IP "check_smime_signature ( )" 4
.IX Item "check_smime_signature ( )"
\&\fIInstance method\fR.
Verifies S/MIME signature of the message,
and if verification succeeded, sets {smime_signed} item true.
.Sp
Parameters:
.Sp
None
.Sp
Returns:
.Sp
1 if signature is successfully verified.
0 otherwise.
\&\f(CW\*(C`undef\*(C'\fR if something went wrong.
.IP "is_signed ( )" 4
.IX Item "is_signed ( )"
\&\fIInstance method\fR.
Checks if the message is signed.
.Sp
\&\fBNote\fR:
This checks if the message has appropriate content type and
header parameters.  Use \fBcheck_smime_signature()\fR to check if the message has
properly signed content.
.Sp
Currently, S/MIME\-signed messages with content type
\&\*(L"multipart/signed\*(R" or \*(L"application/pkcs7\-mime\*(R" (with smime\-type=\*(L"signed\-data\*(R"
parameter) are recognized.
Enveloped-only messages are not supported.
The other signature mechanisms such as \s-1PGP/MIME\s0 have not been supported yet.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
\&\f(CW1\fR if the message is considered signed.
\&\f(CW0\fR otherwise.
.ie n .IP "personalize ( $list, [ $rcpt ] )" 4
.el .IP "personalize ( \f(CW$list\fR, [ \f(CW$rcpt\fR ] )" 4
.IX Item "personalize ( $list, [ $rcpt ] )"
\&\fIInstance method\fR.
Personalizes a message with custom attributes of a user.
.Sp
Parameters:
.RS 4
.ie n .IP "$list" 4
.el .IP "\f(CW$list\fR" 4
.IX Item "$list"
List object.
.ie n .IP "$rcpt" 4
.el .IP "\f(CW$rcpt\fR" 4
.IX Item "$rcpt"
Recipient.
.ie n .IP "$data" 4
.el .IP "\f(CW$data\fR" 4
.IX Item "$data"
Hashref.  Additional data to be interpolated into personalized message.
.RE
.RS 4
.Sp
Returns:
.Sp
Modified message itself, or \f(CW\*(C`undef\*(C'\fR if error occurred.
.RE
.ie n .IP "test_personalize ( $list )" 4
.el .IP "test_personalize ( \f(CW$list\fR )" 4
.IX Item "test_personalize ( $list )"
\&\s-1DEPRECATED\s0 by Sympa 6.2.13.
No longer available.
.Sp
\&\fIInstance method\fR.
Tests if personalization can be performed successfully over all subscribers
of list.
.Sp
Parameters:
.Sp
Returns:
.Sp
\&\f(CW1\fR if succeed, or \f(CW\*(C`undef\*(C'\fR.
.ie n .IP "personalize_text ( $body, $list, [ $rcpt ], [ $data ] )" 4
.el .IP "personalize_text ( \f(CW$body\fR, \f(CW$list\fR, [ \f(CW$rcpt\fR ], [ \f(CW$data\fR ] )" 4
.IX Item "personalize_text ( $body, $list, [ $rcpt ], [ $data ] )"
\&\fIFunction\fR.
Retrieves the customized data of the
users then parses the text. It returns the
personalized text.
.Sp
Parameters:
.RS 4
.ie n .IP "$body" 4
.el .IP "\f(CW$body\fR" 4
.IX Item "$body"
Message body with the \s-1TT2.\s0
.ie n .IP "$list" 4
.el .IP "\f(CW$list\fR" 4
.IX Item "$list"
List object.
.ie n .IP "$rcpt" 4
.el .IP "\f(CW$rcpt\fR" 4
.IX Item "$rcpt"
The recipient email.
.ie n .IP "$data" 4
.el .IP "\f(CW$data\fR" 4
.IX Item "$data"
Hashref.  Additional data to be interpolated into personalized message.
.RE
.RS 4
.Sp
Returns:
.Sp
Customized text, or \f(CW\*(C`undef\*(C'\fR if error occurred.
.RE
.ie n .IP "prepare_message_according_to_mode ( $mode, $list )" 4
.el .IP "prepare_message_according_to_mode ( \f(CW$mode\fR, \f(CW$list\fR )" 4
.IX Item "prepare_message_according_to_mode ( $mode, $list )"
\&\fIInstance method\fR.
Transforms the message according to reception mode:
\&\f(CW\*(Aqmail\*(Aq\fR, \f(CW\*(Aqnotice\*(Aq\fR or \f(CW\*(Aqtxt\*(Aq\fR.
Note: 'html' mode was deprecated as of 6.2.23b.2.
.Sp
By \f(CW\*(Aqnomail\*(Aq\fR, \f(CW\*(Aqdigest\*(Aq\fR, \f(CW\*(Aqdigestplain\*(Aq\fR or \f(CW\*(Aqsummary\*(Aq\fR mode,
the message is not modified.
.Sp
Returns modified message object itself, or \f(CW\*(C`undef\*(C'\fR if transformation failed.
.IP "decorate ($list, [ mode => \fIpersonalization mode\fR ] )" 4
.IX Item "decorate ($list, [ mode => personalization mode ] )"
\&\fIInstance method\fR.
Adds footer/header to a message.
.IP "reformat_utf8_message ( )" 4
.IX Item "reformat_utf8_message ( )"
\&\fIInstance method\fR.
Reformats bodies of text parts contained in the message using
recommended encoding schema and/or charsets defined by MIME::Charset.
.Sp
MIME-compliant headers are appended / modified.  And custom X\-Mailer:
header is appended :).
.Sp
Parameters:
.RS 4
.ie n .IP "$attachments" 4
.el .IP "\f(CW$attachments\fR" 4
.IX Item "$attachments"
ref(\s-1ARRAY\s0) \- messages to be attached as subparts.
.RE
.RS 4
.Sp
Returns:
.Sp
string
.RE
.ie n .IP "shelve_personalization ( type => $type )" 4
.el .IP "shelve_personalization ( type => \f(CW$type\fR )" 4
.IX Item "shelve_personalization ( type => $type )"
\&\fIInstance method\fR.
Shelve personalization (\*(L"merge feature\*(R") if necessary.
\&\f(CW$type\fR is either \f(CW\*(Aqweb\*(Aq\fR or \f(CW\*(Aqmail\*(Aq\fR.
.Sp
Dies if the context of the message was not List.
.IP "get_plain_body ( )" 4
.IX Item "get_plain_body ( )"
\&\fIInstance method\fR.
Gets decoded content of text/plain part.
.Sp
The text will be converted to \s-1UTF\-8.\s0
Flowed text (see \s-1RFC 3676\s0) will be conjuncted.
.IP "check_virus_infection ( [ debug => 1 ] )" 4
.IX Item "check_virus_infection ( [ debug => 1 ] )"
\&\fIInstance method\fR.
Checks the message using anti-virus plugin, if configuration requests it.
.Sp
Parameter:
.Sp
\&\s-1TBD.\s0
.Sp
Returns:
.Sp
The name of malware the message contains, if any;
\&\f(CW"unknown"\fR for unidentified malware;
\&\f(CW\*(C`undef\*(C'\fR if checking failed;
otherwise \f(CW0\fR.
.IP "get_plaindigest_body ( )" 4
.IX Item "get_plaindigest_body ( )"
\&\fIInstance method\fR.
Returns a plain text version of message, suitable for use in plain text
digests.
.RS 4
.IP "\(bu" 4
Most attachments are stripped out and replaced with a
note that they've been stripped. text/plain parts are
retained.
.IP "\(bu" 4
An attempt to convert text/html parts to plain text is made
if there is no text/plain alternative.
.IP "\(bu" 4
All messages are converted from their original character
set to \s-1UTF\-8.\s0
.IP "\(bu" 4
Parts of type message/rfc822 are recursed
through in the same way, with brief headers included.
.IP "\(bu" 4
Any line consisting only of 30 hyphens has the first
character changed to space (see \s-1RFC 1153\s0). Lines are
wrapped at 76 columns.
.RE
.RS 4
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
String.
.RE
.IP "dmarc_protect ( )" 4
.IX Item "dmarc_protect ( )"
\&\fIInstance method\fR.
Munges the \f(CW\*(C`From:\*(C'\fR header field if we are using \s-1DMARC\s0 Protection mode.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
None.
\&\f(CW\*(C`From:\*(C'\fR field of the message may be modified.
.IP "compute_topic ( )" 4
.IX Item "compute_topic ( )"
\&\fIInstance method\fR.
Compute 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
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
String of tag(s), can be separated by ',', can be empty.
.IP "get_id ( )" 4
.IX Item "get_id ( )"
\&\fIInstance method\fR.
Gets unique identifier of instance.
.SS "Context and Metadata"
.IX Subsection "Context and Metadata"
Context and metadata given to constructor are accessible as hash elements of
object.  These are typically used.
.IP "{context}" 4
.IX Item "{context}"
Context of the message, Sympa::List object, robot or \f(CW\*(Aq*\*(Aq\fR.
.IP "{date}" 4
.IX Item "{date}"
The \s-1UNIX\s0 time messages was initially accepted, or the time message should be
delivered.
.IP "{domainpart}" 4
.IX Item "{domainpart}"
.PD 0
.IP "{listname}" 4
.IX Item "{listname}"
.IP "{listtype}" 4
.IX Item "{listtype}"
.IP "{localpart}" 4
.IX Item "{localpart}"
.PD
Domain, name, type and local part of context.
.IP "{priority}" 4
.IX Item "{priority}"
Priority of the message.
.IP "{tag}" 4
.IX Item "{tag}"
Tag of packet used by bulk spool to control logging.
\&\f(CW\*(Aq0\*(Aq\fR is the first message of multiple packet.
\&\f(CW\*(Aqz\*(Aq\fR is the last.
\&\f(CW\*(Aqs\*(Aq\fR is the single message with single packet.
.IP "{time}" 4
.IX Item "{time}"
The Unix time in floating point number when the message was stored into the
spool.  This is used by bulk spool.
.SS "Attributes"
.IX Subsection "Attributes"
These are accessible as hash elements of objects.
.IP "{checksum}" 4
.IX Item "{checksum}"
No longer used.  It is kept for compatibility with Sympa 6.1.x or earlier.
See also \fBupgrade_send_spool\fR\|(1).
.IP "{envelope_sender}" 4
.IX Item "{envelope_sender}"
Envelope sender, a.k.a. \*(L"Unix From\*(R".
This is not always same as {sender} attribute
nor the content of \f(CW\*(C`From:\*(C'\fR field.
.Sp
\&\f(CW\*(Aq<>\*(Aq\fR will be used for \*(L"null envelope sender\*(R".
.IP "{family}" 4
.IX Item "{family}"
Name of family (see Sympa::Family) the message corresponds to.
This is given by \fBfamilyqueue\fR\|(8) program.
.IP "{gecos}" 4
.IX Item "{gecos}"
Display name of actual sender (see {sender} below), if any.
.IP "{md5_check}" 4
.IX Item "{md5_check}"
True value indicates that the message has been authenticated by \f(CW\*(C`md5\*(C'\fR level
(password authentication).
This is set by web mailer of WWSympa and used by incoming spool.
.IP "{message_id}" 4
.IX Item "{message_id}"
Original message \s-1ID\s0 of the message.
.IP "{rcpt}" 4
.IX Item "{rcpt}"
Recipients for delivery.
This is kept for compatibility with earlier releases.
.IP "{sender}" 4
.IX Item "{sender}"
Actual sender of the message.
This is determined according to \f(CW\*(C`sender_headers\*(C'\fR configuration parameter.
See also {envelope_sender} above.
.IP "{shelved}" 4
.IX Item "{shelved}"
Shelved processing.
Hashref with multiple items.
Currently these items are available:
.RS 4
.IP "decorate => 1" 4
.IX Item "decorate => 1"
Adding footer/header if any.
.Sp
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.
.IP "dkim_sign => 1" 4
.IX Item "dkim_sign => 1"
Adding \s-1DKIM\s0 signature.
.IP "dmarc_protect => 1" 4
.IX Item "dmarc_protect => 1"
\&\s-1DMARC\s0 protection.  See also \*(L"dmarc_protect\*(R"().
.ie n .IP "merge => ""footer""|""all""" 4
.el .IP "merge => \f(CWfooter\fR|\f(CWall\fR" 4
.IX Item "merge => footer|all"
Personalizing.
.Sp
On Sympa 6.2.58 or earlier, there was no distinction between \f(CW\*(C`footer\*(C'\fR and \f(CW\*(C`all\*(C'\fR.
The \f(CW\*(C`merge\*(C'\fR item in the messages stored into outgoing spool by earlier version
of Sympa will be treated as \f(CW\*(C`all\*(C'\fR.
.IP "smime_encrypt => 1" 4
.IX Item "smime_encrypt => 1"
Adding S/MIME encryption.
.IP "smime_sign => 1" 4
.IX Item "smime_sign => 1"
Adding S/MIME signature.
.ie n .IP "tracking => ""dsn""|""mdn""|""r""|""w""|""verp""" 4
.el .IP "tracking => \f(CWdsn\fR|\f(CWmdn\fR|\f(CWr\fR|\f(CWw\fR|\f(CWverp\fR" 4
.IX Item "tracking => dsn|mdn|r|w|verp"
Requesting tracking feature including \s-1VERP.\s0
.RE
.RS 4
.Sp
This is used by bulk spool.
.RE
.IP "{spam_status}" 4
.IX Item "{spam_status}"
Result of spam check.
This is set by \*(L"check_spam_status\*(R"() method.
.SS "Serialization"
.IX Subsection "Serialization"
Sympa::Message object includes number of slots as hash items:
\&\fBmetadata\fR, \fBcontext\fR, \fBattributes\fR and \fBmessage content\fR.
Metadata including context are given by spool:
See \*(L"Marshaling and unmarshaling metadata\*(R" in Sympa::Spool.
.PP
Logically, objects are stored into physical spool as \fBserialized form\fR
and deserialized when they are fetched from spool.
\&\fBAttributes\fR will be serialized and deserialized along with raw message
content.
Attributes are encoded in \f(CW\*(C`X\-Sympa\-*:\*(C'\fR pseudo-header fields and
\&\f(CW\*(C`Return\-Path:\*(C'\fR header field.
Below is an example of serialized form.
.PP
.Vb 10
\&  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.                              :    |
\&                                                  :   \-\-\-
.Ve
.PP
On msg, automatic and bounce spools,
\&\f(CW\*(C`Return\-Path:\*(C'\fR header fields are given by \s-1MDA\s0
and \f(CW\*(C`X\-Sympa\-*:\*(C'\fR header fields are given by queue programs.
On other spools, they are given by components of Sympa.
.PP
Pseudo-header fields \fIshould\fR appear at beginning of serialized content.
Fields appear at other places (e.g. \f(CW\*(C`X\-Sympa\-Topic:\*(C'\fR field above) are not
attributes but are the part of raw message content.
.PP
Pseudo-header fields \fIshould not\fR be included in actually sent messages.
.SH "CAVEAT"
.IX Header "CAVEAT"
.ie n .SS "Adding ""Return\-Path:"" field"
.el .SS "Adding \f(CWReturn\-Path:\fP field"
.IX Subsection "Adding Return-Path: field"
We trust in \f(CW\*(C`Return\-Path:\*(C'\fR header field only at the top of message
to prevent forgery.  To ensure it will be added to messages by \s-1MDA,\s0
.IP "Sendmail" 4
.IX Item "Sendmail"
Add \f(CW\*(C`P\*(C'\fR in the \f(CW\*(C`F=\*(C'\fR flags of local mailer line (such as \f(CW\*(C`Mlocal\*(C'\fR).
.IP "Postfix" 4
.IX Item "Postfix"
.RS 4
.PD 0
.IP "\fBlocal\fR\|(8)" 4
.IX Item "local"
.PD
Prepending \f(CW\*(C`Return\-Path:\*(C'\fR is available by default.
.IP "\fBpipe\fR\|(8)" 4
.IX Item "pipe"
Add \f(CW\*(C`R\*(C'\fR to the \f(CW\*(C`flags=\*(C'\fR attributes in master.cf.
.Sp
Additionally with Postfix 2.3 or later, add an empty \f(CW\*(C`null_sender=\*(C'\fR
attribute.
Or \*(L"null envelope sender\*(R" would be replaced with \f(CW\*(C`<MAILER\-DAEMON>\*(C'\fR.
.RE
.RS 4
.RE
.IP "Exim" 4
.IX Item "Exim"
Set \f(CW\*(C`return_path_add\*(C'\fR to be true with pipe_transport.
.IP "qmail" 4
.IX Item "qmail"
Use \fBpreline\fR\|(1).
.IP "sympa-milter" 4
.IX Item "sympa-milter"
As of version 0.7, prepending \f(CW\*(C`Return\-Path:\*(C'\fR is available.
.SH "BUGS"
.IX Header "BUGS"
get_plaindigest_body()
seems to ignore any text after a UUencoded attachment.
.SH "HISTORY"
.IX Header "HISTORY"
Message module appeared on Sympa 3.3.6.
It was initially written by:
.IP "\(bu" 4
Serge Aumont <sa \s-1AT\s0 cru.fr>
.IP "\(bu" 4
Olivier Salau\*:n <os \s-1AT\s0 cru.fr>
.PP
get_plaindigest_body, ex. \*(L"plain_body_as_string\*(R" in PlainDigest,
was initially written by Chris Hastie.  It appeared on Sympa 4.2b.1.
.PP
.Vb 1
\&  (c) Chris Hastie 2004 \- 2008.
.Ve
.PP
Renamed and merged Sympa::Message appeared on Sympa 6.2.