Mailmunge::Context(3)

📦 version 3.20, in alpine 3.24

💖 `Mailmunge::Context(3)` — User Contributed Perl Documentation 💖

okay so bestie, this is the Mailmunge::Context(3) page, and it is <highkey>literally</highkey> the context object era. Buckle up, because we are keeping every single accessor, every single callback name, and every single weird little spelling. No cap. 💅

🎀 NAME 🎀

Mailmunge::Context — Object that holds context for Mailmunge filter callbacks.

💖 ABSTRACT 💖

Mailmunge::Context holds all of the context for Mailmunge filter callbacks. The various pieces of information available are documented in ACCESSORS.

If you have a Mailmunge::Context object called $ctx and you want to access the subject and sender accessors, for example, use this code:

my $subject = $ctx->subject;
my $sender = $ctx->sender;

You can also set values in the context by calling, for example:

$ctx->subject($new_subject);
$ctx->sender($new_sender);

although ngl, the usefulness of doing this is dubious as the new value is not propagated back to the milter.

One exception to this rule is if you want to replace the message body. From filter_message, you can call:

$ctx->new_mime_entity($new_entity);

which will replace the message body with $new_entity. Setting new_mime_entity also updates mime_entity. Slay. ✨

👑 CLASS METHODS 👑

🦋 `Mailmunge::Context->new([$param => $val [, $param2 => $val2]...])` 🦋

Mailmunge::Context constructor. Typically not called by user code; the base filter code takes care of creating Mailmunge::Context object. Main character energy: the base filter code handles it. 💅

🌈 ACCESSORS 🌈

okay bestie, this is the big list. Every accessor, no skipping, no vibes-based omissions. Let’s go. 🦋

🍓 `ambiguous_content`

If MIME::Parser is new enough to detect ambiguous MIME messages, returns 1 if the parsed message was ambiguous or 0 if not. Returns undef if MIME::Parser does not support the ambiguous_content method. Valid only in filter_message and filter_wrapup.

We strongly recommend rejecting or quarantining email messages with ambiguous content; they are a security risk as they could be used to get malware to pass through a security filter by relying on MUAs that parse the content differently from MIME::Parser. This is not a vibe-check situation, bestie. It’s security tea. 😭

🌸 `bounced`

Returns a true value if action_bounce has been called. Available in: filter_message, filter_wrapup.

🎀 `client_port`

The TCP port of the connecting SMTP client. Available in: filter_relay, filter_helo.

🦋 `connecting_ip`

The IP address of the connecting SMTP client. Available in: all filter callbacks.

💜 `connecting_name`

The hostname of the connecting SMTP client, if it passed round-trip reverse DNS. Otherwise, the connecting IP address in square brackets. Available in: all filter callbacks.

🍓 `cwd`

The current working directory in which filter files reside. Available in: filter_sender, filter_recipient, filter_message, and filter_wrapup.

✨ `discarded`

Returns a true value if action_discard has been called. Available in: filter_message, filter_wrapup.

🌈 `emstp_args`

An array reference containing the ESMTP arguments (if any) given to the MAIL From: command.

Available in filter_sender, filter_recipient, filter_message and filter_wrapup.

Yes, it is spelled emstp_args exactly like that. Not a typo I invented, bestie. iykyk. 🫶

👑 `first_recip`

The mailbox given by the first RCPT To: command for this message. Available only in filter_recipient.

🧚 `helo`

The hostname given in the HELO or EHLO command. Available in filter_helo, filter_sender, filter_recipient, filter_message and filter_wrapup.

🌟 `hostip`

The IP address of the host from which this email originated.

In filter_relay, filter_helo, filter_sender and filter_recipient, this accessor is available and is exactly the same as connecting_ip.

In filter_message and filter_wrapup, it is available but may differ from connecting_ip if it was parsed from the message headers.

🎀 `hostname`

The name of the host from which this email originated, if it could be determined, or [hostip] if not.

In filter_relay, filter_helo, filter_sender and filter_recipient, this accessor is available and is exactly the same as connecting_name.

In filter_message and filter_wrapup, it is available but may differ from connecting_name if it was parsed from the message headers.

💖 `in_filter_wrapup`

Returns true in filter_wrapup and false elsewhere. Do not tamper with this value. Like, respectfully, leave it alone. 💅

🦋 `mailmunge_id`

A unique identifier for this message. Available in filter_message and filter_wrapup.

🍓 `message_id`

The Message-ID as parsed from the Message-ID: header. Available in filter_message and filter_wrapup.

👑 `message_quarantined`

Returns true if action_quarantine_entire_message has been called. Available in filter_message and filter_wrapup.

🌸 `mime_entity`

Returns a MIME::Entity object — the page literally writes MIME::Entity <https://metacpan.org/pod/MIME::Entity> — representing the parsed input mail message. Available in filter_message and filter_wrapup.

✨ `my_ip`

Returns the IP address of the MTA daemon process that accepted the connection from the SMTP client. Available in filter_relay and filter_helo.

This information can be retrieved in filter_message and filter_wrapup with:

my $ip = $ctx->sendmail_macro('daemon_addr');

💜 `my_port`

Returns TCP port of the MTA daemon process that accepted the connection from the SMTP client. Available in filter_relay and filter_helo.

This information can be retrieved in filter_message and filter_wrapup with:

my $port = $ctx->sendmail_macro('daemon_port');

🧚 `qid`

Returns the MTA Queue-ID. While it is available in all callback functions, it may be set to NOQUEUE in some of them, depending on the MTA.

If you invoke mailmunge with the -y flag, qid is available in all callbacks if the MTA is Sendmail. If the MTA is Postfix, the qid is only ever reliably available in filter_message and filter_wrapup, but see the documentation of sendmail_macro($macro).

🎀 `rcpt_addr`

The value of the ${rcpt_addr} Sendmail macro (or Postfix emulated version thereof). Available only in filter_recipient.

🦋 `rcpt_host`

The value of the ${rcpt_host} Sendmail macro (or Postfix emulated version thereof). Available only in filter_recipient.

🌈 `rcpt_mailer`

The value of the ${rcpt_mailer} Sendmail macro (or Postfix emulated version thereof). Available only in filter_recipient.

💖 `recipient_esmtp_args`

A hash reference indexed by recipient address. Each element of the hash is an array reference consisting of the ESMTP rcpt-parameters as described in RFC 5321, section 4.1.1.3. recipient_esmtp_args is available only in filter_message and filter_wrapup.

🍓 `recipients`

An arrayref of envelope recipient addresses.

In filter_recipient, it contains a single address (the address associated with the current RCPT To: command).

In filter_message and filter_wrapup, it contains an array of all the recipient addresses.

👑 `sender`

The envelope address of the sender (the address in the MAIL From: command.) Available in filter_sender, filter_recipient, filter_message and filter_wrapup.

🌸 `subject`

The message subject (raw value... not MIME-decoded.) Available in filter_message and filter_wrapup.

✨ `subject_count`

The number of Subject: headers seen in the message. A message with more than one Subject: header is somewhat suspicious. Available in filter_message and filter_wrapup.

💜 `suspicious_chars_in_body`

Returns true if a null character, or a carriage return not followed by a newline, was found in the message body. Available in filter_message and filter_wrapup.

🧚 `suspicious_chars_in_headers`

Returns true if a null character, or a carriage return not followed by a newline, was found in the message headers. Available in filter_message and filter_wrapup.

🎀 `tempfailed`

Returns true if action_tempfail was called. Available in filter_message and filter_wrapup.

🦋 `was_resent`

Returns true if the message contains a secret IP validation header. (See STREAMING MECHANISM in Mailmunge::Action::Stream for more details.) Available in filter_message and filter_wrapup.

part 2 is next, bestie — this was only the first half. 🦋

💅 METHODS 💅

okay so Mailmunge::Context has a bunch of extra methods beyond the accessors, and honestly? This is where it gets juicy. Let's go method by method, bestie — no skips, no cap ✨

`new_mime_entity($entity)`

Replaces mime_entity with $entity, and also signals to Mailmunge that the MTA should replace the original message with the new message $entity. It's giving “new message, who dis” 💅

`privdata($key [,$val])`

Set or get private data. This method lets you store additional data in the context object without interfering with any built-in state. To set some private data, use:

$ctx->privdata('my_key', $some_value);

and to retrieve it:

$some_value = $ctx->privdata('my_key');

The value can be a scalar or reference. The lifetime of the value is the same as the lifetime of the $ctx object, which is only for the current callback; almost all callbacks have a brand-new context object. The only exceptions are filter_message and filter_wrapup, which share a $ctx object.

The $key can be any string you like; however, keys whose names start with '@' are reserved for internal use. If you use a key whose name starts with '@', it might conflict with internal Mailmunge code and cause unexpected behavior. So like… don't do that 🙈

`in_message_context()`

A private function that warns if certain functions are called outside of filter_message or filter_wrapup. It's the vibe check for “bestie, are you even in the right callback rn?” 😭

`message_rejected()`

Returns true if bounced, discarded or tempfailed is true. A quick way to tell if the message won't be delivered is:

if ($ctx->message_rejected) {
    # Don't bother with expensive processing.
    # Message won't be delivered anyway.
}

Literally the “don't waste your energy, queen” method 👑

`sendmail_macro($macro)`

Retrieve the content of the given sendmail macro. Don't include curly braces around long macro names. For example:

my $port = $ctx->sendmail_macro('daemon_port');

Sendmail macros are available in filter_sender, filter_recipient, filter_message and filter_wrapup, although specific macros may be available only at certain stages. For example, with Postfix, by default the i macro is not available until the second call to filter_recipient (if any) or filter_message if there is only one recipient. This is because Postfix does not assign a queue-ID until after the first successful RCPT command. You can change this Postfix behavior by setting smtpd_delay_open_until_valid_rcpt to no — the docs are at http://www.postfix.org/postconf.5.html#smtpd_delay_open_until_valid_rcpt — which causes Postfix to allocate a queue-ID after a successful MAIL command. Extremely specific, but we love that for us 🎀

`mta_macro($macro)`

A synonym for sendmail_macro. Same energy, different label 💖

`get_recipient_mailer($recip)`

Returns the [mailer, host, addr] triplet associated with the given recipient, from the Sendail macros {rcpt_mailer}, {rcpt_host} and {rcpt_addr}. Available in filter_message and filter_wrapup. Triplet slay 🌸

`get_quarantine_dir()`

Creates a brand-new subdirectory under Mailmunge's quarantine directory. If the Path:QUARANTINEDIR constant is not set, or the directory could not be created, returns undef. Otherwise, returns the full path to the directory. It's giving “fresh quarantine folder just dropped” ✨

`canonical_sender()`

Returns Mailmunge::Filter->canonical_email($self->sender) — that's the whole method, and it ate 💅

`canonical_recipients()`

Returns an arrayref of envelope recipient addresses after passing them through Mailmunge::Filter->canonical_email. Canonicalize the whole group chat, basically 🫶

`canonical_first_recipient()`

Returns the canonical version of the first recipient (in other words, the canonical version of $self->recipients->[0]). First recipient gets the main character treatment 👑

`log($level, $msg)`

Log a message to syslog of the specified level. $level must be one of 'emerg', 'alert', 'crit', 'err', 'warning', 'notice', 'info' or 'debug'. No custom levels, bestie — the list is the list 🔥

`action_from_response ($resp)`

Given a Mailmunge::Response object $resp, take the appropriate action. This function operates as follows:

if $resp is not defined, or is not a Mailmunge::Response object, return 0.
If $resp->is_tempfail, call $self->action_tempfail($resp->message) and return 1.
If $resp->is_reject, call $self->action_bounce($resp->message) and return 1.
If $resp->is_discard, call $self->action_discard() and return 1.
Otherwise, return 0.

It's the “read the response, choose your fighter” method 😤

`action_bounce($reply, $code, $dsn)`

Ask the MTA to bounce the message. $reply is the text of the bounce; code is a 3-digit 5xy reply code, and $dsn is a three-numbered 5.x.y DSN code.

Writes the 'B' line to RESULTS to tell the C code to bounce the message.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.) So like… respect the callback boundaries, pls 🚧

`action_discard()`

Ask the MTA to discard the message.

Writes the 'D' line to RESULTS to tell the C code to discard the message.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.) Discard era 💀

`action_tempfail($reply, $code, $dsn)`

Ask the MTA to tempfail the message. $reply is the text of the tempfail response; code is a 3-digit 4xy reply code, and $dsn is a three-numbered 4.x.y DSN code.

Writes the 'T' line to RESULTS to tell the C code to tempfail the message.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.) Temporary fail, permanent attitude 💅

`action_change_header($hdr, $value, $idx)`

Ask the MTA to change the value of header $hdr to $value. $hdr is the header name without a colon and $value is the value of the header. Any embedded carriage returns in $value are removed.

$idx (if supplied) is the 1-based index of the header to change in the case of multiple headers. If $hdr was not present, then the MTA is asked to add it.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.) Header glow-up, but make it RFC-compliant ✨

`action_delete_header($hdr, $idx)`

Ask the MTA to delete the header header $hdr $idx (if supplied) is the 1-based index of the header to delete in the case of multiple headers.

Do not include a colon in the header name.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.) Bye-bye header, don't let the door hit you 🦋

`action_delete_all_headers($hdr)`

Ask the MTA to delete all headers $hdr. Do not include a colon in the header name.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.) It's a header clear-out, and it's iconic 🧹

`change_sender($sender)`

Asks the MTA to change the envelope sender.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.) Sender switch-up, no cap 💌

`add_recipient($recip)`

Asks the MTA to add a recipient to the envelope.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.) Adding to the group chat 📨

`delete_recipient($recip)`

Asks the MTA to delete $recip from the list of envelope recipients.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.) Removed from the chat, respectfully 🙈

`action_add_header($hdr, $val)`

Add a header to the message. $hdr is the header name without a colon and $val is the value of the header. Any embedded carriage returns in $val are removed.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.) New header just dropped 🎀

`action_insert_header($hdr, $val, $pos)`

Add a header to the message in the specified position. $hdr is the header name without a colon and $val is the value of the header. Any embedded carriage returns in $val are removed.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.)

As a special case, if $pos is negative or not supplied, then the header is added at the end, as with action_add_header. Placement matters, bestie 💅

`action_sm_quarantine($reason)`

Ask the MTA to quarantine the message. $reason is the reason for the quarantine.

Note that this is different from Mailmunge's quarantine function. Instead, it ends up calling the Milter function smfi_quarantine.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.) Milter quarantine, not Mailmunge quarantine — important distinction, iykyk 🔥

`action_quarantine_entire_message($reason)`

Quarantines the message in the Mailmunge quarantine directory. $reason is the reason for quarantining. Note that calling this function does not affect disposition of the message. If you do not want the original message delivered, you must call action_bounce or action_discard.

On success, returns the directory in which the message was quarantined. On failure, returns undef.

This method may only be called from filter_message or filter_wrapup (or from functions called while they are active.)

⚠️ Lock in: quarantining does not automatically stop delivery. If you want it gone-gone, you still gotta call action_bounce or action_discard. The way that matters 😭

`copy_or_link($src, $dst)`

Attempt to hard-link the file $src to $dst. $dst must be the full desired path of the destination. If hard-linking fails, copy the file instead.

Returns 1 on success; 0 on failure. Link first, copy as backup — resourceful queen behavior 🧚

AUTHOR

Dianne Skoll <dianne@skollsoft.com> 💖

LICENSE

This code is licensed under the terms of the GNU General Public License, version 2.

Mailmunge::Context(3)