jmap-backup-rs 0.1.0

Backup email from a JMAP account to local .eml files
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

# jmap-backup-rs

Backup email from a JMAP account to local `.eml` files.

`jmap-backup-rs` connects to a JMAP server, queries email, downloads each
message as a raw blob, and stores it under a date-based folder layout:

```text
emails/
  2026/
    06/
      02/
        <email-id>.eml
```

Existing files are skipped, so repeated runs can be used to incrementally update
the backup directory.

## Status

This is an early release. It currently targets Fastmail-friendly defaults and
backs up mail only. Restore, delete detection, mailbox metadata, labels, and
contacts are not implemented.

## Installation

Install from source with Cargo:

```sh
cargo install --git https://git.thaller.ws/athaller/jmap-backup-rs
```

Or clone the repository and build locally:

```sh
git clone https://git.thaller.ws/athaller/jmap-backup-rs.git
cd jmap-backup-rs
cargo build --release
```

The optimized binary will be available at
`target/release/jmap-backup-rs`.

## Usage

Create a JMAP API token with permission to read mail, then pass it with
`JMAP_TOKEN`:

```sh
export JMAP_TOKEN='your-token-here'
cargo run --release -- --backup-folder emails
```

Fastmail is the default endpoint:

```text
https://api.fastmail.com
```

For a different JMAP service, provide the endpoint explicitly:

```sh
jmap-backup-rs \
  --url https://jmap.example.com \
  --redirect-host jmap.example.com \
  --backup-folder emails
```

Command-line options:

```text
-b, --backup-folder <PATH>       Path to the backup folder [default: emails]
-t, --token <TOKEN>              JMAP bearer token [env: JMAP_TOKEN]
    --url <URL>                  JMAP API endpoint [env: JMAP_URL]
    --redirect-host <HOST>       Hosts that redirects may follow [env: JMAP_REDIRECT_HOST]
                                 [default: api.fastmail.com]
-h, --help                       Print help
-V, --version                    Print version
```

## Backup Format

Messages are written as `.eml` files using the message receive date:

```text
<backup-folder>/<year>/<month>/<day>/<email-id>.eml
```

The tool checks for existing filenames before downloading, which keeps reruns
cheap when the backup already contains messages.

## Security Notes

Keep your JMAP token private. Prefer the `JMAP_TOKEN` environment variable over
putting tokens directly in shell history, and revoke the token if it is ever
committed or shared accidentally.

Backups contain the full raw email content, including headers, addresses,
message bodies, and attachments. Store the backup directory somewhere private,
and encrypt it when appropriate.

## Development

Run the formatter and checks before opening a pull request:

```sh
cargo fmt
cargo clippy --all-targets --all-features
cargo test
```

Build a smaller optimized release binary with the custom deploy profile:

```sh
cargo build --profile deploy
```

## License

MIT. See `LICENSE`.