dovemail 0.0.1

Use Microsoft's PNP CLI with email clients.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

# Dovemail

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

                   Check your email, peacefully.
```

`dovemail` is a simple\* utility for bridging Microsoft's official CLI tool,
[`m365`](https://aka.ms/cli-m365), with [Maildir](https://en.wikipedia.org/wiki/Maildir)
email clients.
It enables you to read Outlook messages using clients such as [Aerc](https://aerc-mail.org/),
[Neomutt](https://neomutt.org/), [Mozilla Thunderbird](https://www.thunderbird.net), or
[GNOME Evolution](https://gitlab.gnome.org/GNOME/evolution/-/wikis/home),
in situations where third-party applications are not allowed.
See below: [who is this for?](#who-is-this-for)

Retrieving mail works. Sending mail is WIP.

## Installation

### Install from crates.io

```shell
cargo install dovemail
```

### Docker Pull

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

### Podman Pull

```shell
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`

```shell
nix profile install gitlab:jennydaman/dovemail
```

## Quickstart

1. Run `m365 login`
2. Copy [`./scripts/pull_emails_using_dovemail.sh`](./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:

```shell
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

```shell
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](#usage-with-podman), but replace `podman` with `docker`.

#### Implementation Details

The maildir [spec](https://cr.yp.to/proto/maildir.html) 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](#configuration).

`dovemail` names files after the [seahash](https://crates.io/crates/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.