NAME

wsgetmail - get mail from cloud 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",
"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"
}

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.

CONFIGURATION

For full setup and configuration instructions, see App::wsgetmail.

perldoc App::wsgetmail

ARGUMENTS

--config, --configuration, -c

Path of the primary wsgetmail JSON configuration file to read. This argument is required. The configuration file is documented in the next section.

--options

A string with a JSON object in the same format as the configuration file. Configuration in this object will override the configuration file. You can use this to extend a base configuration. For example, given the configuration in the synopsis above, you can process a second folder the same way by running:

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

--verbose, --debug, -v

Log additional information about each mail API request and any problems delivering mail.

--quiet, -q

In "quiet" mode wsgetmail suppresses its normal output on stdout. This output identifies the configuration file used and how many messages were processed.

If there are any errors this information is sent to stderr after the error messages.

This does not affect the additional logging generated by the verbose/debug flag.

The purpose for "quiet" mode is so that, when running wsgetmail multiple times on a schedule using multiple configuration files, no output is produced unless there are errors, and that output identifies the configuration file used.

--dry-run

Read mail and deliver it to the configured command, but don't run the configured action_on_fetched like deleting messages or marking them as read.

--help, -h

Show this help documentation.

--response-handling

This option shouldn't have to exist.

This option exists because most of the MS Graph API calls can return non-success responses sporadically that aren't related to any visible or actionable issue, and may not even mean that the attempted action failed.

Previous versions of wsgetmail treated all of these as first-class errors, complete with warning messages and aborting the run with a failure status. For an administrator this creates a trickle of non-actionable alerts, unless they choose to ignore all errors and output.

To complicate matters it isn't quite as simple as always ignoring specific error codes. For example, one may want to treat a 404 Not Found status code as success when deleting a message and still consider it to be failure when trying to list the messages in a folder.

Version 0.09 of wsgetmail changed the default handling of some non-success status codes across the board (5xx - server-side errors) and for some specific non-success codes when deleting messages (400 and 404).

This seems to be both safe and comprehensive, but this is based on our observations of operational behavior and does not seem to be supported by documentation.

This option exists to allow administrators to modify or augment these new default behaviors precisely. This option is not intended to be used without at least some understanding of the MS Graph API and how the App::wsgetmail::MS365 module uses it.

See the response_matrix section of App::wsgetmail::MS365 for more information, including a list of recognized labels and a description of the data in the matrix is used.

In addition to the ignore value recognized by App::wsgetmail::MS365 this option also makes use the special value delete, which can be used to remove the built-in defaults.

The value of this option is a JSON list of objects that are used to modify and augment the default response matrix, where each element of the list directs that one or more values be added to, or removed from, the matrix.

The default response matrix could be represented with the JSON:

[
  {
    'value':'ignore',
    'labels':{
      'delete_message': ['400','404'],
      'default':        ['5xx']
    }
  }
]

or, more compactly, as:

--response-matrix='[{"value":"ignore","labels":{"delete_message":["400","404"],"default":["5xx"]}}]'

This directs App::wsgetmail::MS365 to ignore (that is, to treat as closely as possible to success) HTTP status codes 400 and 404 when deleting messages as the post-fetch action, and to ignore all 5xx HTTP status codes (server errors) for all calls.

One case worth mentioning specifically is the API call referred to as get_message_mime_content. When this fails there is no content to process so neither the command nor the follow-up action will be performed. However, in order to maintain the illusion of success for the caller, the method returns a value that indicates that the message was processed, which would cause it to be reflected in the counts if they are emitted.

AUTHOR

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

LICENSE AND COPYRIGHT

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

This is free software, licensed under:

The GNU General Public License, Version 2, June 1991