#outlook #microsoft #clients #message #read #pnp

bin+lib dovemail

Use Microsoft's PNP CLI with email clients

1 unstable release

0.0.1 May 3, 2024

#12 in #outlook

Custom license

24KB
361 lines

Dovemail

                    _                                _ _ 
                   | |                              (_) |
  <(' ) /"""/    __| | _____   _____ _ __ ___   __ _ _| |
    \  /   /    / _` |/ _ \ \ / / _ \ '_ ` _ \ / _` | | |
     \.___"    | (_| | (_) \ V /  __/ | | | | | (_| | | |
                \__,_|\___/ \_/ \___|_| |_| |_|\__,_|_|_|

                   Check your email, peacefully.

dovemail is a simple* utility for bridging Microsoft's official CLI tool, m365, with Maildir email clients. It enables you to read Outlook messages using clients such as Aerc, Neomutt, Mozilla Thunderbird, or GNOME Evolution, in situations where third-party applications are not allowed. See below: who is this for?

Retrieving mail works. Sending mail is WIP.

Installation

Install from crates.io

cargo install dovemail

Docker Pull

docker pull registry.gitlab.com/jennydaman/dovemail/master:latest

Podman Pull

podman pull registry.gitlab.com/jennydaman/dovemail/master:latest

Installation Using Nix Flakes

Various methods.

Using Home-Manager

  1. Add inputs.dovemail.url = "gitlab:jennydaman/dovemail"; to ~/.home-manager/config/flake.nix
  2. Add inputs.dovemail.packages.${system}.default to home.packages
  3. Run home-manager switch

Using nix profile

nix profile install gitlab:jennydaman/dovemail

Quickstart

  1. Run m365 login
  2. Copy ./scripts/pull_emails_using_dovemail.sh and run it.

Design

Dovemail's design is "*simple" in the UNIX philosophy sense of "do one thing and one thing well." This repository provides:

  • dovemail, a "simple" Rust program
  • pull_emails_using_dovemail.sh, a not-so-simple Bash script

Usage: dovemail

dovemail parses JSON from stdin and writes plaintext files to an output directory. Typical usage looks like:

m365 outlook message list | dovemail ~/.local/share/mail/bill_gates@example.com/AllMail/tmp
mv ~/.local/share/mail/bill_gates@example.com/AllMail/{tmp,new}

Usage with Podman

podman run --rm \
  -v $HOME/.cli-m365-all-connections.json:/home/cli-microsoft365/.cli-m365-all-connections.json:ro \
  -v $HOME/.cli-m365-connection.json:/home/cli-microsoft365/.cli-m365-connection.json:ro \
  -v $HOME/.cli-m365-msal.json:/home/cli-microsoft365/.cli-m365-msal.json:ro \
  docker.io/m365pnp/cli-microsoft365:latest m365 outlook message list \
  | podman run --rm -i -v $HOME/.local/share/mail/bill_gates@example.com/AllMail/tmp:/out registry.gitlab.com/jennydaman/dovemail/master:latest dovemail /out

Usage with Docker

Same as Usage with Podman, but replace podman with docker.

Implementation Details

The maildir spec describes a procedure for producing unique names, which dovemail does not implement. To my knowledge, this deviation from the spec is benign. You can rename these files to conform to the spec, see the section on Configuration.

dovemail names files after the seahash output on the Outlook message ID.

Usage: pull_emails_using_dovemail.sh

pull_emails_using_dovemail.sh creates a maildir-organized directory in ~/.local/share/mail and runs m365 outlook message list | dovemail ... for each folder to retrieve emails from Outlook. On first run, all messages are downloaded. On subsequent run, only new messages are downloaded.

Configuration

You're on your own. Create a copy pull_emails_using_dovemail.sh and change it however you'd like.

It'll be useful to create a cron/systemd timer/email client hotkey for running (your copy of pull_emails_using_dovemail.sh).

Example: TODO

Who is this for?

Most users hoping to connect mail clients with Outlook should not use Dovemail. One should try the following, in this order:

  1. Connecting directly to Outlook IMAP/SMTP. https://support.microsoft.com/en-us/office/pop-imap-and-smtp-settings-for-outlook-com-d088b986-291d-42b8-9564-9c414e2aa040
  2. Run the Davmail gateway. https://davmail.sourceforge.net/
  3. Use m365 CLI and dovemail.

Dovemail should only be used in situations where third-party applications are disabled by administrator.

Is this allowed?

Use at your own risk!

In situations where third-party applications are being restricted by an administrator, would a tool like dovemail be allowed? Observe that third-party applications are blocked from using Outlook's API. Importantly, dovemail does not use Outlook's API. It never connects with Microsoft's servers — it simply parses the output of m365, an official Microsoft tool. When using dovemail, only first-party software are used to communicate with Microsoft's servers.

Categorically, dovemail is more similar to accessibility software like screen-readers than a third-party client. It interfaces with first-party software (the m365 CLI) and presents data to the user in a more accessible format (maildir, plaintext). If your organization allows disabled persons to use screen readers, there is no technical reason why dovemail should be disallowed.

Computer security policy is often written for people with no computer knowledge, by people with no computer knowledge.

Limitations

Mail attachments are not supported.

Most limitations of dovemail can be worked around by opening the email in a web browser by using the X-Web-Link header.

Dependencies

~6–12MB
~142K SLoC