view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

- command

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

- command\_args

    Set this to a string with additional arguments to pass to `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.

- command\_timeout

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

- action\_on\_fetched

    Set this to a literal string `"mark_as_read"` or `"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 `"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.

- dump\_messages

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

    When `"debug"` is also set the filenames will be reported on STDERR.

- debug

    Set this to enable additional diagnostic and status messages.

- quiet

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

    When in `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.

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

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

# LIMITATIONS

## 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 `--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 `secret` or `user_password` with `--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

## Office 365 API Limits

Microsoft applies some limits to the amount of API requests allowed as
documented in their [Microsoft Graph throttling guidance](https://docs.microsoft.com/en-us/graph/throttling).
If you reach a limit, requests to the API will start failing with HTTP
status code 429 for a period of time.

## Office 365 API Errors

Best Practical Solutions has observed that very rarely the Microsoft Graph API
will return a 5xx error code when attempting to list mail folder details,
retrieve the message list, fetch message details, or delete a message. The
cause for this is currently unknown, except that it is not related to the API
limits mentioned above.

Despite the relative rarity, if you run wsgetmail often enough you can see this
multiple times in a typical day.

Therefore, by default wsgetmail now ignores `5xx` response codes on all API
calls, instead treating them as logically empty success response.

# SEE ALSO