How to use FOLIO APIs to query emails sent to patrons

(condensed from a Slack discussion on the FOLIO implementers channel on August 24 2020)

use the mod-email APIs:
- https://dev.folio.org/reference/api/#mod-email
use GET /email to your Okapi instance to return emails that have been sent to your patrons
- /email can accept CQL queries
- use Limit to return more than the first ten elements that are found in your response.
- the account you are querying the API with must have permission email.message.collection.get which is not visible in the UI.

Example:

Query to GET /email on an Okapi instance returned JSON messages that looked like this (some content snipped):

{
      "notificationId": "9bb7424a-55ec-4f48-b2c6-cb3557ef44d0",
      "to": "erin.nettifee@duke.edu",
      "header": "Activate your Folio account",
      "outputFormat": "text/plain",
      "body": SNIP
      "attachments": [],
      "status": "FAILURE",
      "message": "The 'mod-email' module doesn't have a minimum config for SMTP server, the min config is: [EMAIL_SMTP_PORT, EMAIL_PASSWORD, EMAIL_SMTP_HOST, EMAIL_USERNAME]",
      "date": "2020-02-07T14:34:40.350+0000",
      "metadata": {
        "createdDate": "2020-02-07T14:34:40.278+0000",
        "createdByUserId": "77100dc9-c53c-5df6-a798-066b9b5813e1",
        "updatedDate": "2020-02-07T14:34:40.278+0000",
        "updatedByUserId": "77100dc9-c53c-5df6-a798-066b9b5813e1"
      },
      "deliveryChannel": "email",
      "id": "940f53a3-4bfe-43ee-9cb7-6342e67511c5"
    },

Note that it returned a Failure message. If messages are successful, they are purged from the mod-email repository at a defined interval:
Every 30 mins a scheduled job in launched within mod-email which deletes all emails successfully sent (status = "Delivered") more than 24 hours ago.

The interval between two consecutive runs of this job is configured through mod-email's ModuleDescriptor.json, so potentially libraries can change it during module deployment.
The age of discarded emails is not configurable for this job, but one can call its API manually with the desired expiration date specified as a request parameter.