NAME

Mail::Foundry - Perl extension for talking to a MailFoundry appliance

SYNOPSIS

use Mail::Foundry;
my $mf = new Mail::Foundry(foundry => 'http://mailfoundry.domain.tld/',
                           username => 'admin',
                           password => '3u4ksufZeiu82');

$mf->connect
  or die "Error connecting: " . join(' ', $mf->errors) . "\n";

$mf->add_domain(domain => 'clientdomain.tld',
                server => 'box24.hostdomain.tld');

$mf->add_user( username => 'demo', password => 'mydemo',
               domain => 'clientdomain.tld',
               firstname => 'Joe', lastname => 'User' );

$mf->delete_domain(domain => 'clientdomain.tld');

DESCRIPTION

Mail::Foundry performs web requests via LWP to edit MaiFoundry appliance settings, including adding, removing, and editing domain settings.

add_domain

Adds a new domain to the server for processing and associates the domain with an SMTP server (which the MailFoundry server will relay to).

Parameters:

domain: Required. Specify the domain name to scan mail for.
server: Required. Specify the name of the SMTP server that MailFoundry should relay mail to after scanning. This is often the name of the physical server where domain is hosted.
priority: Optional. Specify the MX priority at which this SMTP server will receive mail. Default: 10.
port: Optional. Specify the TCP port at which this SMTP server will receive mail. Default: 25.
max_msg_size: Optional. Specify (in megabytes) the maximum message size MailFoundry should accept for this domain. Default: 0 (no limit).
virus: Optional. Specify whether we should scan mail for viruses for this domain. Values: 'enable', 'disable'. Default: 'enable'.

delete_domain

Deletes a domain from the server; mail will no longer be accepted by MailFoundry for this domain. Make sure that you have already pointed the MX record to the new server at least 24h beforehand (or whatever your MX TTL is set to).

Parameters:

domain: Required. Specify the domain name to remove from the MailFoundry server.

update_domain

Same parameters as add_domain

add_user

Adds a user to the Mail Foundry server for administering domain names.

Parameters

username: The username with which this user logs into the Mail Foundry server.
password: The password with which this user logs into the Mail Foundry server.
firstname: First name of the login user.
lastname: Last name of the login user.
domain: The name of the domain this user will administer. The domain should have already been added to the system.

update_user

Updates current user information with the provided information.

Parameters: same as add_user with the exception of an additional newusername which will change the username of the user to newusername.

Example:

$mf->update_user( username => 'joe', password => 'mynewpassword' );

This will update joe's password to 'mynewpassword'.

delete_user

Deletes the user from the system, orphaning any domains previously associated with this user.

Parameters:

username

spam_settings

This method returns the current anti-spam settings for this domain when no parameters (other than domain) are given. Otherwise, it sets new anti-spam settings for the domain as specified in the options below.

Parameters:

domain

Required. The domain whose anti-spam settings you wish to modify.

spam_status

Optional. Enables or disables spam scanning for this domain.

Values: enabled | disabled

Default: enabled

spam_act

Optional. Determines the action to take when a spam message is detected.

Values: addh | redir | modsub | quar | delete

addh: add header
redir: redirect spam to email address (specified in redir_email)
modsub: modify subject (specified in modsub)
quar: quarantine spam
delete: delete spam

Default: modsub

s_modsub

Optional. Determines how the subject line is modified when a spam is detected.

Default: '***SPAM***'

redir_email

Optional. Specifies an email address redirect spam to when detected.

Default: (none)

virus_settings

This method returns the current anti-virus settings for this domain when no parameters (other than domain) are given. Otherwise, it sets new anti-virus settings for the domain as specified in the options below.

Parameters:

domain

Required. The domain whose anti-virus settings you wish to modify.

virus_status

Optional. Enables or disables virus scanning for this domain.

Values: enabled | disabled

Default: enabled

virus_act

Optional. Determines the action to take when a virus is received.

Values: clean | modsub | quar | return | delete

clean: clean the message, add 'X-MailFoundry: Virus' header, and deliver
modsub: clean the message, modify the subject line to (v_modsub), and deliver
quar: clean the message and quarantine it
return: return the message to the sender
delete: delete the message

v_modsub

Optional. Determines how the subject line is modified when a virus is received.

Default: 'MAILFOUNDRY: VIRUS DETECTED'

notify_sender

Optional. If set, MailFoundry will send a notification to the sender that a virus was found in an email.

Values: 0 | 1

tell_me

Optional. If set, MailFoundry will send a notification to the recipient that a virus was found in an email.

Values: 0 | 1

smtp_settings

This method returns the current SMTP settings for this domain when no parameters (other than domain) are given. Otherwise, it sets new SMTP settings for the domain as specified in the options below.

domain: Required. The domain whose SMTP settings you wish to view or modify.
server: FIXME: working here

DIAGNOSTICS

When an error occurs internally, the specified action (e.g., add_domain(), delete_domain()) will return undef. You can check diagnostic messages by reading the errors() method:

$mf->add_domain('foo.tld', 'bar.mail.tld')
  or die "Could not add domain: " . join(' ', $mf->errors);

When an error condition occurs, it's probably best to manually login to the MailFoundry server and verify what you wanted to accomplish actually occurred.

Below are diagnostic messages grouped by their associated action.

add_domain()

"The domain already exists.": The domain has already been added.
"Could not verify that the domain was added.": After attempting to add the domain, the mailfoundry server sent an unrecognized response back.
"Could not update the SMTP association settings.": The domain was successfully added but the mailfoundry server sent an unrecognized response when we tried to associate the domain with an existing SMTP server.
"Could not add new server to SMTP destinations.": The domain was successfully added but the MailFoundry server sent an unrecognized response when we tried to associate the domain with a new SMTP server.

delete_domain()

"Failure: XXX: (some HTTP error message)": An HTTP error occurred while requesting the delete domain page.
"Could not get account id from server.": The account id was not found on this server. This may indicate the domain has already been deleted, or it may indicate that the account id is listed on another page (which we haven't parsed).
"The domain could not be verified as deleted.": The domain may have been deleted, but we received an unexpected response from the MailFoundry server.

errors

Returns a list of current errors. Useful for debugging, for example:

unless( $mf->connect ) {
  die "Could not connect to mf server: " . join(' ', $mf->errors) . "\n";
}

err_pages

Returns a list of HTTP::Response objects (usually only the last one) when an error condition or unexpected return value from the MailFoundry server was received. Useful for debugging:

unless( $mf->connect ) {
  my $err = join(' ', $mf->errors);
  unless( $err =~ /domain already exists/ ) {
    die "Unexpected HTML from MailFoundry: " . ($mf->err_pages)[0]->content;
  }
}

If you encounter bugs with this module, the author may ask you to return the results of err_pages.

AUTHOR

Scott Wiersdorf, <scott@perlcode.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.

To install Mail::Foundry, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mail::Foundry

CPAN shell

perl -MCPAN -e shell
install Mail::Foundry

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

add_domain

delete_domain

update_domain

add_user

update_user

delete_user

spam_settings

virus_settings

smtp_settings

DIAGNOSTICS

add_domain()

delete_domain()

errors

err_pages

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions