view release on metacpan or  search on metacpan

lib/App/wsgetmail.pm  view on Meta::CPAN

# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
# 02110-1301 or visit their web page on the internet at
# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
#
#
# CONTRIBUTION SUBMISSION POLICY:
#
# (The following paragraph is not intended to limit the rights granted
# to you to modify and distribute this software under the terms of
# the GNU General Public License and is only of importance to you if
# you choose to contribute your changes and enhancements to the
# community by submitting them to Best Practical Solutions, LLC.)
#
# By intentionally submitting any modifications, corrections or
# derivatives to this work, or any other work intended for use with
# Request Tracker, to Best Practical Solutions, LLC, you confirm that
# you are the copyright holder for those contributions and you grant
# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
# royalty-free, perpetual, license to use, copy, create derivative
# works based on those contributions, and sublicense and distribute
# those contributions and any derivatives thereof.
#
# END BPS TAGGED BLOCK }}}

use v5.10;

package App::wsgetmail;

use Moo;

our $VERSION = '0.11';

=head1 NAME

App::wsgetmail - Fetch mail from the cloud using webservices

=head1 SYNOPSIS

Run:

    wsgetmail [options] --config=wsgetmail.json

where C<wsgetmail.json> looks like:

    {
    "client_id": "abcd1234-xxxx-xxxx-xxxx-1234abcdef99",
    "tenant_id": "abcd1234-xxxx-xxxx-xxxx-123abcde1234",
    "secret": "abcde1fghij2klmno3pqrst4uvwxy5~0",
    "global_access": 1,
    "username": "rt-comment@example.com",
    "folder": "Inbox",
    "stripcr": 0,
    "size_limit": 10485760,
    "body_size_limit": 1048576,
    "command": "/opt/rt5/bin/rt-mailgate",
    "command_args": "--url=http://rt.example.com/ --queue=General --action=comment",
    "command_timeout": 30,
    "action_on_fetched": "mark_as_read"
    }

Using App::wsgetmail as a library looks like:

    my $getmail = App::wsgetmail->new({config => {
      # The config hashref takes all the same keys and values as the
      # command line tool configuration JSON.
    }});
    while (my $message = $getmail->get_next_message()) {
        $getmail->process_message($message)
          or warn "could not process $message->id";
    }

=head1 DESCRIPTION

wsgetmail retrieves mail from a folder available through a web services API
and delivers it to another system. Currently, it only knows how to retrieve
mail from the Microsoft Graph API, and deliver it by running another command
on the local system.

=head1 INSTALLATION

    perl Makefile.PL
    make
    make test
    sudo make install

C<wsgetmail> will be installed under C</usr/local/bin> if you're using the
system Perl, or in the same directory as C<perl> if you built your own.

=cut

use Clone 'clone';
use Module::Load;
use App::wsgetmail::MDA;

=head1 ATTRIBUTES

=head2 config

A hash ref that is passed to construct the C<mda> and C<client> (see below).

=cut

has config => (
    is => 'ro',
    required => 1
);

=head2 mda

An instance of L<App::wsgetmail::MDA> created from our C<config> object.

=cut

has mda => (
    is => 'rw',
    lazy => 1,
    handles => [ qw(forward) ],

lib/App/wsgetmail.pm  view on Meta::CPAN

=back

=head2 Configuring the mail delivery command

Now that you've configured wsgetmail to access a mail account, all that's
left is configuring delivery. Set the following in your wsgetmail
configuration file.

=over 4

=item folder

Set this to the name string of a mail folder to read.

=item stripcr

Set this to 1 to make wsgetmail convert the messages from the CRLF
line-ending encoding to the LF line-ending encoding.

This emulates the fetchmail option of the same name, which enabled
the stripcr option if an MDA was declared. The feature is similar,
but you need to enable it explicitly in your configuration.

This option is helpful if you are forwarding email to a Linux
utility that doesn't work with CRLF line-endings.

=item size_limit

Set this to the max size in bytes. Messages bigger than it will be skipped.
Absence or 0 means to not limit size.

E.g. to skip messages bigger than C<10MiB>, you can set it to C<10485760>.

=item body_size_limit

Set this to the max body size in bytes. Messages with body bigger than it will
be skipped. Absence or 0 means to not limit body size.

E.g. to skip messages with body bigger than C<1MiB>, you can set it to
C<1048576>.

The difference between C<size_limit> and C<body_size_limit> is the former
limits the size of the whole message, while the latter parses messages, skips
attachments and only checks text/plain and text/html parts.

=item command

Set this to an executable command. You can specify an absolute path,
or a plain command name which will be found from C<$PATH>. For each
email wsgetmail retrieves, it will run this command and pass the
message data to it via standard input.

=item command_args

Set this to a string with additional arguments to pass to C<command>.
These arguments follow shell quoting rules: you can escape characters
with a backslash, and denote a single string argument with single or
double quotes.

=item command_timeout

Set this to the number of seconds the C<command> has to return before
timeout is reached.  The default value is 30.  Use "inf" for no timeout.

=item action_on_fetched

Set this to a literal string C<"mark_as_read"> or C<"delete">.
For each email wsgetmail retrieves, after the configured delivery
command succeeds, it will take this action on the message.

If you set this to C<"mark_as_read">, wsgetmail will only retrieve and
deliver messages that are marked unread in the configured folder, so it does
not try to deliver the same email multiple times.

=item dump_messages

Set this to 1 to preserve the temporary files after processing.

When C<"debug"> is also set the filenames will be reported on STDERR.

=item debug

Set this to enable additional diagnostic and status messages.

=item quiet

Set this to put wsgetmail into C<quiet> mode. This mode intended for use in cron
or other automation.

When in C<quiet> mode wsgetmail produces no output unless there is an error, in
which case the configuration filename and error messages will be printed to
STDERR.

=back

=head1 TESTING AND DEPLOYMENT

After you write your wsgetmail configuration file, you can test it by running:

    wsgetmail --debug --dry-run --config=wsgetmail.json

This will read and deliver messages, but will not mark them as read or
delete them. If there are any problems, those will be reported in the error
output. You can update your configuration file and try again until wsgetmail
runs successfully.

Once your configuration is stable, you can configure wsgetmail to run
periodically through cron or a systemd service on a timer.

=head1 ERRORS AND DIAGNOSTIC MESSAGES

wsgetmail sends warning, error, and debug messages to STDERR, while purely
informational messages are sent to STDOUT.  Operators may want to capture both
output streams as a merged stream for diagnostic purposes.  For example:

    wsgetmail --debug --dry-run --config=wsgetmail.json > wsgetmail.debug 2>&1

When the mail processing command exits with an error (non-zero) status the
action_on_fetched is not performed on that message so that it will be processed
on the next run.