Scroll to navigation

Courier::Filter::Module::Envelope(3pm) User Contributed Perl Documentation Courier::Filter::Module::Envelope(3pm)


Courier::Filter::Module::Envelope - Message envelope filter module for the Courier::Filter framework


    use Courier::Filter::Module::Envelope;
    my $module = Courier::Filter::Module::Envelope->new(
        fields      => {
            # One or more of the following fields:
            sender              => '',
            recipient           => '',
            remote_host         => '',
            remote_host_name    => qr/(^|\.)php\.net$/,
            remote_host_helo    => qr/^[^.]*$/
        # Optionally the following:
        response    => $response_text,
        logger      => $logger,
        inverse     => 0,
        trusting    => 0,
        testing     => 0,
        debugging   => 0
    my $filter = Courier::Filter->new(
        modules     => [ $module ],


This class is a filter module class for use with Courier::Filter. It matches a message if one of the message's envelope fields matches the configured criteria.


The following constructor is provided:

Creates a new Envelope filter module.

%options is a list of key/value pairs representing any of the following options:

Required. A reference to a hash containing the message envelope field names and patterns (as key/value pairs) that messages are to be matched against. Field names are matched case-insensitively. Patterns may either be simple strings (for exact, case-sensitive matches) or regular expression objects created by the "qr//" operator (for inexact, partial matches).

The following envelope fields are supported:

The message's envelope sender (from the "MAIL FROM" SMTP command).
Any of the message's envelope recipients (from the "RCPT TO" SMTP commands).
The IP address of the SMTP client that submitted the message.
The host name (gained by Courier through a DNS reverse lookup) of the SMTP client that submitted the message, if available.
The HELO string that the SMTP client specified, if available.

So for instance, to match any message with a sender of "", directed at "" (possibly among other recipients), you could set the "fields" option as follows:

    fields      => {
        sender      => '',
        recipient   => ''
A string that is to be returned literally as the match result in case of a match. Defaults to "Prohibited <field>: <value>".

All options of the Courier::Filter::Module constructor are also supported. Please see "new()" in Courier::Filter::Module for their descriptions.

Instance methods

See "Instance methods" in Courier::Filter::Module for a description of the provided instance methods.


Courier::Filter::Module::Header, Courier::Filter::Module, Courier::Filter::Overview.

For AVAILABILITY, SUPPORT, and LICENSE information, see Courier::Filter::Overview.


Julian Mehnle <>

2022-10-21 perl v5.34.0