view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# NAME

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

# SYNOPSIS

Run:

    wsgetmail [options] --config=wsgetmail.json

where `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";
    }

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

# INSTALLATION

    perl Makefile.PL
    make
    make test
    sudo make install

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

# ATTRIBUTES

## config

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

## mda

An instance of [App::wsgetmail::MDA](https://metacpan.org/pod/App%3A%3Awsgetmail%3A%3AMDA) created from our `config` object.

## client\_class

The name of the App::wsgetmail package used to construct the
`client`. Default `MS365`.

## client

An instance of the `client_class` created from our `config` object.

# METHODS

## process\_message($message)

Given a Message object, retrieves the full message content, delivers it
using the `mda`, and then executes the configured post-fetch
action. Returns a boolean indicating success.

## post\_fetch\_action($message)

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

# CONFIGURATION

## Configuring Microsoft 365 Client Access

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

- Client Credentials

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

- Username/password

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

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

- 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 ["Set up a tenant"
    quickstart](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant). Save
    this as the `tenant_id` string in your wsgetmail configuration file.

- client\_id

    You need to register wsgetmail as an application in your Azure Active
    Directory tenant. Microsoft documents how to do this in the ["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 `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
    ["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 the following items:

    - Mail.Read
    - Mail.ReadWrite

### Configuring client secret authentication

We recommend you deploy wsgetmail by configuring it with a client
secret. Client secrets can be granted limited access to only the mailboxes
you choose. You can adjust or revoke wsgetmail's access without interfering
with other applications.

Microsoft documents how to create a client secret in the ["Register an
application with the Microsoft identity platform"
quickstart](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#add-a-client-secret),
under the section "Add a client secret." Take care to record the secret
token when it appears; it will never be displayed again. It should look like
a completely random string, not a UUID/GUID.

- global\_access

    Set this to `1` in your wsgetmail configuration file.

- secret

    Set this to the secret token string you recorded earlier in your wsgetmail
    configuration file.

- username

    wsgetmail will fetch mail from this user's account. Set this to an email
    address string in your wsgetmail configuration file.