Mail::M...:Forward(3)

📦
version 4.04 · 11 versions
, in fedora 44

💖 NAME 💖

Hiii bestie, welcome to Mail::Message::Construct::Forward — the whole entire point of this page is forwarding a Mail::Message. That's it. That's the job. 👑

✨ SYNOPSIS ✨

my Mail::Message $forward = $message->forward(To => 'you');
$forward->send;

🌸 DESCRIPTION 🌸

So here's the tea: all the complex functionality that lives on Mail::Message objects is actually spread across a bunch of different files, and those files get autoloaded whenever you need them. ✨

This particular file? This one handles everything to do with creating forwarded messages. That's its whole personality and honestly, slay. 💅

👑 METHODS 👑

🧵 Constructing a message

$obj->forward(%options)

Forward the content of this message, bestie. 🫶 The body of the message you're forwarding gets wrapped up in some accompanying text — and if you do not want that accompanying text at all, then bounce is the move for you instead. On success you get a Mail::Message object back. Iconic.

You can forward a whole entire message, but you can also forward just message parts. And if you're feeling impatient, you can overrule some of the default header settings for the reply right away — or you can just do it later with set on the header. Your call, main character. 💅

When a multi-part body shows up and the message is included to ATTACH, the parts that look like signatures get removed. If only one message is left after that, it gets added as a single attachment — otherwise you end up with a nested multipart. Also: the value of this option doesn't matter at all, as long as it's present. Wild, but okay. See Mail::Message::Body::Multipart for the deets.

Defaults, laid out for you boo:

  • Bcc — default: undef
  • Cc — default: undef
  • Date — default: <now>
  • From — default: <'to' in current>
  • Message-ID — default: <uniquely generated>
  • Subject — default: forwardSubject()
  • To — default: <required>
  • body — default: undef
  • include — default: 'NO' if body is set, otherwise 'INLINE'
  • preamble — default: constructed from prelude and postlude
  • signature — default: undef

Now the actual options, one by one, no skipping:

  • Bcc => $string|$address|\@addresses — the receivers of the blind carbon copies. Their names will not be published to the other message receivers. Sneaky. 🕵️
  • Cc => $string|$address|\@addresses — the carbon-copy receivers. By default? Nobody. None. Zero. 🎀
  • Date => DATE — the date to be used in the message that gets sent.
  • From => $string|$address|\@addresses — your identification. By default it's taken from the To field of the source message. Yes really. 👀
  • Message-ID => STRING — hand over a STRING to be the specific message-id for the forwarded message. By default one gets generated for you. And if your id doesn't have angle brackets around it? They get added. 💫
  • Subject => STRING|CODE — force the subject line to be that specific STRING, or use whatever the subroutine in CODE returns. That subroutine gets called with the subject of the original message as its only argument. By default, the forwardSubject() method is what's used.
  • To => $string|$address|\@addresses — where your message is going. Obligatory. The addresses can be a string, a Mail::Address object, or an ARRAY of Mail::Address objects.
  • body => $body — if you pass in a fully prepared $body object, that's what gets used as the forwarded message contents. In that case only the headers get constructed for you. Teamwork. 🤝
  • include => 'NO'|'INLINE'|'ATTACH'|'ENCAPSULATE' — does the message you're replying to have to be included in the message? When you say INLINE, you can also pass along the options of forwardInline(). In a lot of applications, the forward option "as attachment" produces a structure that's what you get when this option is set to ENCAPSULATE. Their default behavior is usually INLINE. Also important: it's only possible to inline textual messages, so binary or multi-part messages will always be enclosed as an attachment. Read the details in section "Creating a forward". 📚
  • preamble => STRING|$body — the part that gets attached before the forwarded message. If no preamble is given, it's constructed from the prelude and postlude. And if those aren't present either? You still get a one-liner: the result of forwardPrelude(). Never say never. 💖
  • signature => $body|$message — the signature to add in the case of a multi-part forward. The mime-type of the signature body should indicate that it's being used as one of those. However! In INLINE mode, the body gets taken, a line containing -- gets added before it, and it gets added behind the epilogue. 🎀

$obj->forwardAttach(%options)

Forward the message as a flat attachment onto the preamble you specify. You can specify every option that forward() takes, though a preamble provided as a body object is required, and any body you specify gets ignored. Sorry bestie, that's the rules. 🙈

  • preamble — default: <required>
  • preamble => BODY|PART

$obj->forwardEncapsulate(%options)

Like forwardAttach(), except in this case the original message gets encapsulated first as a nested message inside a Mail::Message::Body::Nested, and then it's joint into a multipart. 🧚

You can specify all the options that forward() takes, though a preamble provided as a body object is required, and any body you specify gets ignored. Signatures are not stripped. Signatures are not stripped. (Yeah, it says it twice. And the second time? Still true. Signatures are NOT stripped. 💀)

  • preamble — default: <required>
  • preamble => BODY|PART

$obj->forwardInline(%options)

This method is behaviorally equivalent to forward() with the include option set to 'INLINE'. You can specify most of the fields available to forward() — except include and body. 😭

  • is_attached — default: "[The forwarded message is attached]\n"
  • max_signature — default: 10
  • postlude — default: undef
  • prelude — default: undef
  • quote — default: undef
  • strip_signature — default: qr/^--\s/
  • is_attached => STRING — a forward on binary messages can't be inlined, so those get automatically translated into an attachment, exactly as made by forwardAttach(). The obligatory preamble option of that method can be specified as an option to this method too, so it's there for when you're forwarding a binary — but otherwise it's constructed from the prelude, the value of this option, and the postlude.
  • max_signature => INTEGER — passed to Mail::Message::Body::stripSignature(max_lines). Only effective for single-part messages. 🍓
  • postlude => $body — the line(s) to be added after the quoted reply lines. Create a body for it first! This should not include the signature — that has its own option. The signature gets added after the postlude when the forwarded message is INLINEd.
  • prelude => $body — the line(s) added before the quoted forwarded lines. If nothing is specified, the result of the forwardPrelude() method is used. When undef is specified, no prelude gets added at all. ✨
  • quote => CODE|STRING — mangle the lines of an INLINEd reply using CODE, or by prepending a STRING to each line. The routine specified by CODE gets called when the line is in $_. By default, nothing gets added before each line. This option gets processed after the body has been decoded. 🧠
  • strip_signature => REGEXP|STRING|CODE — remove the sender's signature. The value of this parameter is passed to Mail::Message::Body::stripSignature(pattern), unless the source text isn't included. The signature is stripped from the message before quoting. 💅

$obj->forwardNo(%options)

Construct a forward where the whole body of the message is already constructed. That complex body is usually produced in forwardInline(), forwardAttach(), or forwardEncapsulate(). Look at the little ecosystem go. 🦋

The %options are the same as for forward() — except that body is required. Some other options, like preamble, get ignored.

  • body — default: <required> (the original spells this table header -Option--Default, and honestly, we respect the chaos 💀)
  • body => BODY

$obj->forwardPostlude()

Added after the forwarded message. 🎀

» example:

---- END forwarded message

$obj->forwardPrelude()

Create a few lines to be included before the forwarded message content. The return value is an array of lines.

» example:

---- BEGIN forwarded message
From: him@somewhere.else.nl (Original Sender)
To: me@example.com (Me the receiver)
Cc: the.rest@world.net
Date: Wed, 9 Feb 2000 15:44:05 -0500
<blank line>

$obj->forwardSubject(STRING)

Create a subject for a message that's a forward from this one. This routine tries to count the level of reply in the subject field and transform it into a standard form. And listen — please contribute improvements. The author is literally asking. Bestie behavior. 🫶

» example:

subject                 --> Forw: subject
Re: subject             --> Forw: Re: subject
Re[X]: subject          --> Forw: Re[X]: subject
<blank>                 --> Forwarded
okay that's part 1, we're not done yet — keep scrolling, there's more coming 💖

✨ DETAILS ✨

💖 Creating a forward 💖

okay bestie, so the tea here is that bounce() and forward() are NOT the same girl, even if they look similar from far away. the whole reason for processing the message is different.

with a bounce, the vibe is: "we're not touching the content, we're just passing the exact same info along somewhere else". sure, maybe a little conversion happens on the way, but like, the Message-ID doesn't need to change at all. it's the same message, just relocated. slay.

with a forward, though? the entire point is that the information gets modified — annotated or reduced. and important distinction: it does not go back to the author of the original message (that's what reply() does, different queen entirely) — it goes to someone else.

so the flow is: some info comes in → gets modified → gets forwarded to someone else. iconic. and right now there are four ways to get the original info included, and we're gonna go through each one in the next sections 💅

oh and also — after you create the forward, you might wanna rebuild() the message to strip out unnecessary complexities. totally optional though, not required, do what feels right 🫶

🌸 forward, specify a body

when you specify forward(body), you've created your own body object to be used as the content of the forwarded message. which means forward(include) is 'NO' — no automatic generation of the forwarded body, you're doing it yourself, main character energy.

🦋 forward, inline the original

here, forward(include) is set to 'INLINE' (which is the default, btw). this is the most complicated situation, but it's also the one MUAs use the most: the original message gets inserted textually into the new body. you can set up automatic stripping of signatures, choose the way of encapsulation, and pick texts that should be added before and after the encapsulated part. very customizable, we love that.

but bestie, the result may not always be what you expect 😭 for instance, some people use very long signatures which will NOT be automatically stripped because they pass the threshold. so you probably need some manual intervention after the message is created and before it's sent. no cap.

and when a binary message shows up? inlining is literally impossible. in that case, the message is treated as if 'ENCAPSULATE' was requested. the code just handles it for you, periodt.

🎀 forward, attach the original

when forward(include) is explicitly set to 'ATTACH', the result is a multipart containing two parts:

  • the first part = your message
  • the second part = the body of the original message

this means the headers of the forwarded message are used for the new message, and they're detached from the part that now holds the original body info. content-related headers will (of course) still be part of that part, but headers like "To" and "Subject" will not be stored with that part.

as an example of the structural transformation:

# code: $original->printStructure;
multipart/alternative: The source message
  text/plain: content in raw text
  text/html: content as html

# code: $fwd = $original->forward(include => 'ATTACH');
# code: $fwd->printStructure
multipart/mixed: The source message
  text/plain: prelude/postlude/signature
  multipart/alternative
    text/plain: content in raw text
    text/html: content as html

💜 forward, encapsulate the original

when forward(include) is explicitly set to 'ENCAPSULATE', the original message is left in-tact as good as possible ✨ the lines of the original message are used in the main message header but also enclosed in the part header.

the encapsulation is implemented using a nested message, content type "message/rfc822". example of the structural transformation:

# code: $original->printStructure;
multipart/alternative: The source message
  text/plain: content in raw text
  text/html: content as html

# code: $fwd = $original->forward(include => 'ENCAPSULATE');
# code: $fwd->printStructure
multipart/mixed: The source message
  text/plain: prelude/postlude/signature
  message/rfc822
     multipart/alternative: The source message
        text/plain: content in raw text
        text/html: content as html

so yeah, the message structure is much more complex, but literally no information is lost. and honestly? that's probably why so many MUAs use this when they forward an original message as an attachment. it ate. 👑

🩺 DIAGNOSTICS 🩺

  • Error: Cannot include forward source as $kind. — unknown alternative for the forward(include). the valid choices are "NO", "INLINE", "ATTACH", and "ENCAPSULATE". cast by forward()
  • Error: method forwardAttach requires a preamble. — cast by forwardAttach()
  • Error: method forwardEncapsulate requires a preamble. — cast by forwardEncapsulate()
  • Error: method forwardNo requires a To. — cast by forwardNo()
  • Error: method forwardNo requires a body. — cast by forwardNo()

👀 SEE ALSO 👀

this module is part of Mail-Message version 4.04, built on February 04, 2026. website: http://perl.overmeer.net/CPAN/ 🌐

📜 LICENSE 📜

for contributors, see file ChangeLog.

this software is copyright (c) 2001-2026 by Mark Overmeer.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. fr fr, go wild but respect the terms 💖

and that's a wrap on this page, bestie!! 🎀 this came to you courtesy of perl v5.42.0, dated 2026-02-05, and it's the Mail::M...:Forward(3) manual page — go forth and forward responsibly 💅✨🦋

📦 where this page comes from