/ 
Mail-Alias-LocalFile-0.01
/ Mail::Alias::LocalFile

NAME

Mail::Alias::LocalFile - A module for resolving email aliases and building recipient lists from a locally maintained aliases file. The MTA shared aliases file may stll be used when and if desired.

SYNOPSIS

use Mail::Alias::LocalFile;

$resolver = Mail::Alias::LocalFile->new(aliases => $alias_file_href);
$result = $resolver->resolve_recipients($intended_recipients_aref);

# Get the final comma-separated list of recipients
my $recipients = $result->{recipients};

# Check for any warnings
if (@{$result->{warning}}) {
    print "Warnings: ", join("\n", @{$result->{warning}}), "\n";
}


You can also detect all circular references in  the local aliases file:

    $resolver = Mail::Alias::LocalFile->new(aliases => $alias_file_href);
    $circular = $resolver->detect_circular_references($alias_file_ref);
    my @circular_references = @{$circular};
    if ( $circular_references[0] ) {
        print "Circular references detected: ", join("\n", @circular_references), "\n";
    }

DESCRIPTION

The Mail::Alias::LocalFile module provides functionality to resolve email addresses and aliases into a unique list of email recipients. It handles nested aliases, validates email addresses, and detects circular references in alias definitions.

This module is particularly useful for applications that need to expand distribution lists or group aliases into actual email addresses while ensuring uniqueness and validity.

Use of the system aliases file when desired is supported via the special alias prefix 'mta_'. Values with the prefix 'mta_' will not be expanded locally but will be passed to the MTA for expansion. The 'mta_' prefix will be stripped before passing to the MTA.

Alias keys with the 'mta_' prefix are not allowed and will be skipped with a warning.

    my $aliases = {
        'group2' => 'Mary@example.com, Joe@example.com'
        'system' => 'mta_postmaster',
        'normal' => 'normal@example.com',
    };

    use Mail::Alias::LocalFile;

    my $resolver   = Mail::Alias::LocalFile->new(aliases => $aliases);
    my $result     = $resolver->resolve_recipients([ bill@example.com group2 system ]);
    my $recipients = $result->{recipients};

    The recipients email addresses to pass to your email client code is:
        'bill@example.com,mary@example,com,joe@example.com,postmaster'

	group2 and mta_postmaster are expanded from the local aliases file
	and the postmaster alias will expand from  the system wide aliases file

OUTPUT Returns a hash_ref:

$result{recipients} 
$result{warning}
$result{original_input}
$result{aliases}
$result{processed_aliases}
$result{expanded_addresses}
$result{uniq_email_addresses}
$result{mta_aliases}

Where $result{recipients} is the comma separated expanded email addresses and MTA aliases suitable for use in the To: field of your email code

Always check $result{warning} to identify problems encountered, if any. The other available result values are useful for troubleshooting

ATTRIBUTES

warning

An array reference storing warning messages generated during processing.

$resolver->warning(["Warning message"]);
my $warnings = $resolver->warning;

aliases

A hash reference mapping alias names to their values (either strings or array references). This attribute is required when creating a new instance. It is provided from your application after your application loads a locally maintained aliases file.

my $resolver   = Mail::Alias::LocalFile->new(aliases => $aliases);
my $aliases = $resolver->aliases;

This is how Perl sees your local alias file data for parsing.

expanded_addresses

An array reference containing the cumulative expanded email addresses (including duplicates as each item from the input is expanded

my $all_addresses = $resolver->expanded_addresses;

For troubleshooting if your result is not as expected.

addresses_and_aliases

An array reference. A working copy of the original_input that is consumed by shift, to provide each item of the array for analysis.

original_input

An array reference containing the original input provided to resolve_recipients.

my $result     = $resolver->resolve_recipients([ bill@example.com group2 system ]);
my $original = $resolver->original_input;

Stored for troubleshooting purposes, if needed.

processed_aliases

A hash reference tracking which aliases have been processed and used to avoid duplicate processing and suppress circular references (if any).

my $processed = $resolver->processed_aliases;

uniq_email_addresses

An array reference containing the final list of unique email addresses after expansion and deduplication.

my $unique = $resolver->uniq_email_addresses;

mta_aliases

An array reference containing aliases that should be passed to the MTA for expansion after the 'mta_' prefix has been removed. Not used unless the local alias has a value containing an alias with the mta_ prefix. The mta_ prefix must be used in order to pass an alias through for expansion by the MTA alias file.

my $mta_aliases = $resolver->mta_aliases;

METHODS

resolve_recipients

Expands a list of addresses and aliases into a unique list of email addresses.

my $result = $resolver->resolve_recipients(['team', 'john@example.com']);

Returns a hash reference with the following keys:

  • expanded_addresses: All expanded addresses (including duplicates)

  • uniq_email_addresses: Unique email addresses after deduplication

  • recipients: Comma-separated string of unique addresses and MTA aliases

  • original_input: Original input provided

  • warning: Any warnings generated during processing

  • aliases: Reference to the original aliases hash

  • processed_aliases: Aliases that were processed

  • mta_aliases: Aliases designated to be processed by the MTA

extract_addresses_from_list

Processes a single element that might contain multiple addresses or aliases.

$resolver->extract_addresses_from_list('john@example.com, team');

process_single_item

Processes a single item, determining if it's an email address, an alias, or an MTA-delegated alias.

$resolver->process_single_item('john@example.com');

process_mta_alias

Processes an MTA-delegated alias (with 'mta_' prefix).

$resolver->process_mta_alias('postmaster');

process_potential_email

Validates and normalizes a potential email address.

$resolver->process_potential_email('John@Example.COM');

process_potential_alias

Processes an alias name, expanding it if found.

$resolver->process_potential_alias('team');

expand_alias

Expands an alias into its constituent addresses and/or other aliases.

$resolver->expand_alias('team');

remove_duplicate_email_addresses

Removes duplicate email addresses from the expanded list.

my $unique_addresses = $resolver->remove_duplicate_email_addresses();

detect_circular_references

Detects circular references in the alias definitions.

my @circular = $resolver->detect_circular_references($aliases);

Returns an array of strings describing any circular references found, with each string showing the path of the circular reference (e.g., "team -> dev-team -> team").

check_circular

Internal recursive function to check for circular references.

process_item

Internal function to process individual items when checking for circular references.

DEPENDENCIES

  • Moo

  • namespace::autoclean

  • Email::Valid

  • Scalar::Util

  • Data::Dumper::Concise

  • Types::Standard

AUTHOR

Russ Brewer (RBREW) rbrew@cpan.org

VERSION

0.01

SEE ALSO

  • Email::Valid->address

  • Moo