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 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.

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

ACCESSORS

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.

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

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.

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 if action_quarantine_entire_message has been called. Available in filter_message and filter_wrapup.

mime_entity

Returns a MIME::Entity object 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.

METHODS

Mailmunge::Context has additional methods beyond the accessors.

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.

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.

in_message_context()

A private function that warns if certain functions are called outside of filter_message or filter_wrapup.

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.
}

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, which causes Postfix to allocate a queue-ID after a successful MAIL command.

mta_macro($macro)

A synonym for sendmail_macro.

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.

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

canonical_sender()

Returns Mailmunge::Filter->canonical_email($self->sender)

canonical_recipients()

Returns an arrayref of envelope recipient addresses after passing them through Mailmunge::Filter->canonical_email

canonical_first_recipient()

Returns the canonical version of the first recipient (in other words, the canonical version of $self->recipients->[0])

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'

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.

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.