view release on metacpan or  search on metacpan

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

        unlink $filename or warn "couldn't delete message file $filename : $!";
    }
    return $ok;
}

=head2 post_fetch_action($message)

Given a Message object, executes the configured post-fetch action. Returns a
boolean indicating success.

=cut

sub post_fetch_action {
    my ($self, $message) = @_;
    my $method = $self->_post_fetch_action;
    my $ok = 1;
    # check for dry-run option
    if ($self->config->{dry_run}) {
        warn "dry run so not running $method action on fetched mail";
        return 1;
    }
    if ($method) {
        $ok = $self->$method($message->id);
    }
    return $ok;
}

###

sub _build_client {
    my $self = shift;
    my $classname = 'App::wsgetmail::' . $self->client_class;
    load $classname;
    my $config = clone $self->config;
    $config->{post_fetch_action} = $self->_post_fetch_action;
    return $classname->new($config);
}


sub _build_mda {
    my $self = shift;
    my $config = clone $self->config;
    if ( defined $self->config->{username}) {
        $config->{recipient} //= $self->config->{username};
    }
    return App::wsgetmail::MDA->new($config);
}

=head1 CONFIGURATION

=head2 Configuring Microsoft 365 Client Access

To use wsgetmail, first you need to set up the app in Microsoft 365.
Two authentication methods are supported:

=over

=item Client Credentials

This method uses shared secrets and is preferred by Microsoft.
(See L<Client credentials|https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-authentication-flows#client-credentials>)

=item Username/password

This method is more like previous connections via IMAP. It is currently
supported by Microsoft, but not recommended. (See L<Username/password|https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-authentication-flows#usernamepassword>)

=back

This section walks you through each piece of configuration wsgetmail needs,
and how to obtain it.

=over 4

=item tenant_id

wsgetmail authenticates to an Azure Active Directory (AD) tenant. This
tenant is identified by an identifier that looks like a UUID/GUID: it should
be mostly alphanumeric, with dividing dashes in the same places as shown in
the example configuration above. Microsoft documents how to find your tenant
ID, and create a tenant if needed, in the L<"Set up a tenant"
quickstart|https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant>. Save
this as the C<tenant_id> string in your wsgetmail configuration file.

=item client_id

You need to register wsgetmail as an application in your Azure Active
Directory tenant. Microsoft documents how to do this in the L<"Register an
application with the Microsoft identity platform"
quickstart|https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application>,
under the section "Register an application." When asked who can use this
application, you can leave that at the default "Accounts in this
organizational directory only (Single tenant)."

After you successfully register the wsgetmail application, its information
page in your Azure account will display an "Application (client) ID" in the
same UUID/GUID format as your tenant ID. Save this as the C<client_id>
string in your configuration file.

After that is done, you need to grant wsgetmail permission to access the
Microsoft Graph mail APIs. Microsoft documents how to do this in the
L<"Configure a client application to access a web API"
quickstart|https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis#application-permission-to-microsoft-graph>,
under the section "Add permissions to access Microsoft Graph." When selecting
the type of permissions, select "Application permissions." When prompted to
select permissions, select all of the following:

=over 4

=item * Mail.Read

=item * Mail.Read.Shared

=item * Mail.ReadWrite

=item * Mail.ReadWrite.Shared

=item * openid

=item * User.Read

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

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.

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

Full output of the processing command is produced with C<--debug>.

=head1 LIMITATIONS

=head2 Fetching from Multiple Folders

wsgetmail can only read from a single folder each time it runs. If you need
to read multiple folders (possibly spanning different accounts), then you
need to run it multiple times with different configuration.

If you only need to change a couple small configuration settings like the
folder name, you can use the C<--options> argument to override those from a
base configuration file. For example:

    wsgetmail --config=wsgetmail.json --options='{"folder": "Inbox"}'
    wsgetmail --config=wsgetmail.json --options='{"folder": "Other Folder"}'

NOTE: Setting C<secret> or C<user_password> with C<--options> is not secure
and may expose your credentials to other users on the local system. If you
need to set these options, or just change a lot of settings in your
configuration, just run wsgetmail with different configurations:

    wsgetmail --config=account01.json
    wsgetmail --config=account02.json

=head2 Office 365 API Limits

Microsoft applies some limits to the amount of API requests allowed as
documented in their L<Microsoft Graph throttling guidance|https://docs.microsoft.com/en-us/graph/throttling>.
If you reach a limit, requests to the API will start failing for a period
of time.

=head1 SEE ALSO

=over 4

=item * L<wsgetmail>

=item * L<App::wsgetmail::MDA>

=item * L<App::wsgetmail::MS365>

=item * L<App::wsgetmail::MS365::Message>

=back

=head1 AUTHOR

Best Practical Solutions, LLC <modules@bestpractical.com>

=head1 LICENSE AND COPYRIGHT

This software is Copyright (c) 2015-2022 by Best Practical Solutions, LLC.

This is free software, licensed under:

The GNU General Public License, Version 2, June 1991

=cut

1;