fastmail-sieve 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fastmail_sieve-0.1.0/.gitignore +7 -0
- fastmail_sieve-0.1.0/LICENSE +21 -0
- fastmail_sieve-0.1.0/NOTICE +46 -0
- fastmail_sieve-0.1.0/PKG-INFO +329 -0
- fastmail_sieve-0.1.0/README.md +298 -0
- fastmail_sieve-0.1.0/pyproject.toml +66 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/__init__.py +0 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/__main__.py +5 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/cli.py +102 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/__init__.py +22 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/_options.py +30 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/assemble.py +27 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/auth.py +154 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/diff.py +30 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/doctor.py +16 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/explain.py +60 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/folders.py +30 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/init.py +95 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/lint.py +42 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/migrate.py +29 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/pull.py +31 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/commands/push.py +52 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/config.py +61 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/doctor.py +101 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/__init__.py +0 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/auth_discovery.py +100 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/auth_input.py +41 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/blocks.py +181 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/credentials.py +279 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/jmap.py +59 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/mailboxes.py +107 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/project.py +57 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/remote.py +28 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/__init__.py +0 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/format.py +121 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/lint.py +149 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/migrate.py +246 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/report.py +728 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/script.py +83 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/variable_docs.py +32 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/variables.py +205 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/warnings.py +8 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/wording.py +339 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/steps.py +225 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/ui/__init__.py +0 -0
- fastmail_sieve-0.1.0/src/fastmail_sieve/ui/tables.py +53 -0
- fastmail_sieve-0.1.0/tests/__init__.py +0 -0
- fastmail_sieve-0.1.0/tests/test_auth.py +144 -0
- fastmail_sieve-0.1.0/tests/test_auth_status.py +300 -0
- fastmail_sieve-0.1.0/tests/test_blocks.py +307 -0
- fastmail_sieve-0.1.0/tests/test_check_sieve.py +94 -0
- fastmail_sieve-0.1.0/tests/test_cli.py +155 -0
- fastmail_sieve-0.1.0/tests/test_commands.py +332 -0
- fastmail_sieve-0.1.0/tests/test_config.py +120 -0
- fastmail_sieve-0.1.0/tests/test_credentials.py +213 -0
- fastmail_sieve-0.1.0/tests/test_doctor.py +198 -0
- fastmail_sieve-0.1.0/tests/test_documented_commands.py +44 -0
- fastmail_sieve-0.1.0/tests/test_init.py +251 -0
- fastmail_sieve-0.1.0/tests/test_jmap.py +116 -0
- fastmail_sieve-0.1.0/tests/test_no_variation_selectors.py +19 -0
- fastmail_sieve-0.1.0/tests/test_packaging.py +32 -0
- fastmail_sieve-0.1.0/tests/test_remote.py +60 -0
- fastmail_sieve-0.1.0/tests/test_sieve_blocks.py +103 -0
- fastmail_sieve-0.1.0/tests/test_sieve_folders.py +128 -0
- fastmail_sieve-0.1.0/tests/test_sieve_format.py +216 -0
- fastmail_sieve-0.1.0/tests/test_sieve_migrate.py +296 -0
- fastmail_sieve-0.1.0/tests/test_sieve_push.py +353 -0
- fastmail_sieve-0.1.0/tests/test_sieve_report.py +667 -0
- fastmail_sieve-0.1.0/tests/test_sieve_variables.py +208 -0
- fastmail_sieve-0.1.0/tests/test_sieve_warnings.py +96 -0
- fastmail_sieve-0.1.0/tests/test_tables.py +67 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Hugo Haas
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
fastmail-sieve
|
|
2
|
+
Copyright (c) 2026 Hugo Haas, released under the MIT license (see LICENSE).
|
|
3
|
+
|
|
4
|
+
This project builds on the work of the following project.
|
|
5
|
+
|
|
6
|
+
Fastmail-Sieve-Sync
|
|
7
|
+
https://github.com/fuyu0425/Fastmail-Sieve-Sync
|
|
8
|
+
|
|
9
|
+
Fastmail-Sieve-Sync showed that Fastmail's private SieveBlocks/get and
|
|
10
|
+
SieveBlocks/set JMAP methods exist and what fields they carry. fastmail-sieve
|
|
11
|
+
reimplements, in its own code and from reading that source, the way it:
|
|
12
|
+
|
|
13
|
+
- reads the six parts of the script (require, start, blocked, middle, rules
|
|
14
|
+
and end) and joins them with newlines into the full script;
|
|
15
|
+
- writes back only the start, middle and end blocks;
|
|
16
|
+
- recognises the "Managed by Sieve Sync" markers around those blocks, leaves
|
|
17
|
+
them as it finds them, and replaces the text between them.
|
|
18
|
+
|
|
19
|
+
Scripts that have no markers get fastmail-sieve's own ("Managed by
|
|
20
|
+
fastmail-sieve") instead. Both styles are recognised so that a script already
|
|
21
|
+
managed with Fastmail-Sieve-Sync keeps working. No source file was copied
|
|
22
|
+
verbatim. The license of Fastmail-Sieve-Sync follows.
|
|
23
|
+
|
|
24
|
+
----------------------------------------------------------------------------
|
|
25
|
+
|
|
26
|
+
MIT License
|
|
27
|
+
|
|
28
|
+
Copyright (c) 2023 Yu-Fu Fu
|
|
29
|
+
|
|
30
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
31
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
32
|
+
in the Software without restriction, including without limitation the rights
|
|
33
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
34
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
35
|
+
furnished to do so, subject to the following conditions:
|
|
36
|
+
|
|
37
|
+
The above copyright notice and this permission notice shall be included in all
|
|
38
|
+
copies or substantial portions of the Software.
|
|
39
|
+
|
|
40
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
41
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
42
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
43
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
44
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
45
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
46
|
+
SOFTWARE.
|
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: fastmail-sieve
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Keep Fastmail Sieve rules in git: lint, explain, migrate and sync. Unofficial.
|
|
5
|
+
Project-URL: Homepage, https://github.com/hugoh/fastmail-sieve
|
|
6
|
+
Project-URL: Issues, https://github.com/hugoh/fastmail-sieve/issues
|
|
7
|
+
Project-URL: Repository, https://github.com/hugoh/fastmail-sieve
|
|
8
|
+
Author: Hugo Haas
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
License-File: NOTICE
|
|
12
|
+
Keywords: email,fastmail,filters,jmap,sieve
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Communications :: Email :: Filters
|
|
22
|
+
Classifier: Topic :: Utilities
|
|
23
|
+
Requires-Python: >=3.11
|
|
24
|
+
Requires-Dist: keyring>=25
|
|
25
|
+
Requires-Dist: rich<15,>=14
|
|
26
|
+
Requires-Dist: sievelib<1.7,>=1.6
|
|
27
|
+
Provides-Extra: auth
|
|
28
|
+
Requires-Dist: browser-cookie3; extra == 'auth'
|
|
29
|
+
Requires-Dist: pycryptodomex; extra == 'auth'
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# fastmail-sieve
|
|
33
|
+
|
|
34
|
+
Keep your Fastmail Sieve rules in git, and lint, explain, diff and push them
|
|
35
|
+
from the command line. **Unofficial**: not made or supported by Fastmail, and
|
|
36
|
+
it uses an undocumented Fastmail API that can change without notice (see
|
|
37
|
+
[How it works](#how-it-works)).
|
|
38
|
+
|
|
39
|
+
- **Edit rules as files** in three fragments (`rules/top.sieve`,
|
|
40
|
+
`rules/middle.sieve`, `rules/bottom.sieve`), review them in git, and push
|
|
41
|
+
them to Fastmail.
|
|
42
|
+
- **`lint`** is the one check: format, syntax (including Fastmail's own Sieve
|
|
43
|
+
extensions such as `jmapquery` and `mailboxid`), variables, and that every
|
|
44
|
+
folder id in your rules still exists with the right name. It ends with
|
|
45
|
+
warnings (overlaps, duplicates, disabled rules). `lint --fix` reformats your
|
|
46
|
+
rules.
|
|
47
|
+
- **`explain`** shows your rules and your Fastmail UI rules in plain language,
|
|
48
|
+
the whole script, or its variables.
|
|
49
|
+
- **`migrate`** turns your Fastmail UI rules into custom Sieve rules.
|
|
50
|
+
- **`push`** shows the diff and asks before it changes anything.
|
|
51
|
+
|
|
52
|
+
## How it works
|
|
53
|
+
|
|
54
|
+
Fastmail builds your Sieve script from several parts: its own generated code
|
|
55
|
+
(spam, blocked senders, your Settings > Filters & Rules), and three places
|
|
56
|
+
for your own code that run before and after those parts. `fastmail-sieve`
|
|
57
|
+
reads the whole script, shows you all of it, and only ever writes those three
|
|
58
|
+
blocks, which are your three fragment files.
|
|
59
|
+
|
|
60
|
+
Each block is wrapped in a pair of marker comments, which must stay where they
|
|
61
|
+
are:
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
#### Managed by fastmail-sieve: start ####
|
|
65
|
+
#### Managed by fastmail-sieve: end ####
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`init --remote` adds them to a script that has none. A script that was
|
|
69
|
+
managed with [Fastmail-Sieve-Sync](#relationship-to-fastmail-sieve-sync)
|
|
70
|
+
already has its `Managed by Sieve Sync Start` and `End` markers; those are
|
|
71
|
+
recognised too and left as they are.
|
|
72
|
+
`init --remote --convert-markers` replaces them with this tool's own markers,
|
|
73
|
+
after asking: your rules are untouched, but Sieve-Sync no longer recognises the
|
|
74
|
+
blocks, so it is a one-way step.
|
|
75
|
+
|
|
76
|
+
Fastmail has no official API for this. The tool calls the private
|
|
77
|
+
`SieveBlocks/get` and `SieveBlocks/set` JMAP methods that Fastmail's own
|
|
78
|
+
Sieve editor uses, with the token and cookie of a logged-in web session (see
|
|
79
|
+
[Credentials](#credentials)). **That can break at any time** and carries the
|
|
80
|
+
risks described there. `fastmail-sieve doctor` tells you what works for your
|
|
81
|
+
account, and whether Fastmail now advertises an official Sieve API (RFC 9661)
|
|
82
|
+
that this tool could use instead.
|
|
83
|
+
|
|
84
|
+
## Install
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
uv tool install fastmail-sieve # or: pipx install fastmail-sieve
|
|
88
|
+
uvx fastmail-sieve --help # or run it without installing
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Python 3.11 or newer. The optional `auth` extra (`fastmail-sieve[auth]`) is
|
|
92
|
+
only for `auth --discover`. The command is also installed as `fmsieve`.
|
|
93
|
+
|
|
94
|
+
## Quick start
|
|
95
|
+
|
|
96
|
+
```sh
|
|
97
|
+
mkdir my-sieve && cd my-sieve
|
|
98
|
+
fastmail-sieve init # rules/, variables.toml, .gitignore
|
|
99
|
+
fastmail-sieve auth # store your token and cookie (see Credentials)
|
|
100
|
+
fastmail-sieve init --remote # once: add the managed blocks to Fastmail
|
|
101
|
+
fastmail-sieve pull # bring Fastmail's current blocks into rules/
|
|
102
|
+
$EDITOR rules/middle.sieve
|
|
103
|
+
fastmail-sieve lint --fix # reformat, then check everything
|
|
104
|
+
fastmail-sieve diff # what a push would change
|
|
105
|
+
fastmail-sieve push # shows the diff, asks, pushes, verifies
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Commands
|
|
109
|
+
|
|
110
|
+
| Command | Does |
|
|
111
|
+
|---------|------|
|
|
112
|
+
| `init` | Create `rules/`, `variables.toml` and a `.gitignore` line; never overwrites. `--remote` also adds the managed blocks to Fastmail's script (once, asks first); `--convert-markers` also replaces Sieve-Sync's marker comments with this tool's own (one way) |
|
|
113
|
+
| `auth` | Check the token and cookie against Fastmail and store them in the keychain. `auth status` shows which credentials are available and where each comes from |
|
|
114
|
+
| `doctor` | Check the project files, the credentials and what Fastmail lets them do |
|
|
115
|
+
| `pull` | Overwrite the three fragments with Fastmail's managed blocks (commit first: local edits are lost) |
|
|
116
|
+
| `push` | Check everything, show the diff, ask, push the managed blocks, then verify with a fresh pull. `--yes` skips the question |
|
|
117
|
+
| `diff` | Show what a push would change (`+` added, `-` removed) |
|
|
118
|
+
| `assemble` | Print the full script (Fastmail's parts plus your fragments); `--output FILE` writes it |
|
|
119
|
+
| `lint` | The one check, as a checklist that stops at the first failure: format and syntax of your rules, then the assembled script (syntax, markers, variables), the folder stable ids and names, and finally the warnings (overlaps, duplicate or conflicting UI rules, disabled UI rules, stale variable descriptions), which are shown but do not fail. `--fix` reformats your rules first (indentation and `:mailboxid` folder names); `--strict` makes warnings fail; `--offline` skips everything that needs Fastmail; `--from-file FILE` checks a saved script |
|
|
120
|
+
| `explain [TOPIC]` | `rules` (the default): a summary table, then your rules and your UI rules as tables. `script`: the whole script in execution order. `variables`: the script's variables and where they are set and read |
|
|
121
|
+
| `migrate` | Print custom rules equivalent to your enabled Fastmail UI rules |
|
|
122
|
+
| `folders` | List Fastmail folders and their ids (`folders tax` filters by path) |
|
|
123
|
+
|
|
124
|
+
Commands that need the script (`assemble`, `diff`, `explain`, `lint`,
|
|
125
|
+
`migrate`) fetch it themselves; pass `--from-file FILE` to use a
|
|
126
|
+
saved copy with no network. `fastmail-sieve COMMAND --help` lists the options.
|
|
127
|
+
|
|
128
|
+
## Credentials
|
|
129
|
+
|
|
130
|
+
`fastmail-sieve` needs the **browser session token and cookie** of a logged-in
|
|
131
|
+
Fastmail session. Fastmail has no Sieve scope for API tokens, so a normal API
|
|
132
|
+
token cannot read or write the script (it is enough for folder lookups, see
|
|
133
|
+
below).
|
|
134
|
+
|
|
135
|
+
> **The token and cookie are a full web session.** Whoever has both can act as
|
|
136
|
+
> you in Fastmail: read, send and delete mail, change filters (including
|
|
137
|
+
> forwarding rules) and create API tokens. Treat them like your password.
|
|
138
|
+
> Logging out of that session in Fastmail revokes them. How long a pair lasts is
|
|
139
|
+
> not documented by Fastmail.
|
|
140
|
+
|
|
141
|
+
### Getting them
|
|
142
|
+
|
|
143
|
+
1. In a browser signed in to Fastmail, open Settings > Filters & Rules > Edit
|
|
144
|
+
custom Sieve code, and open the developer tools on the Network tab.
|
|
145
|
+
2. Edit anything in the Sieve box and click Save. Then cancel the edit: do not
|
|
146
|
+
keep it.
|
|
147
|
+
3. Find the request that appears (a POST to `api.fastmail.com`).
|
|
148
|
+
4. Either right-click it and choose Copy > Copy as cURL, then run
|
|
149
|
+
`pbpaste | fastmail-sieve auth --stdin` (the command is read from standard
|
|
150
|
+
input, so nothing secret lands in your shell history), or copy the value
|
|
151
|
+
after `Authorization: Bearer` (it starts with `fma1-`) and the `Cookie`
|
|
152
|
+
header and run `fastmail-sieve auth` to paste them into two hidden prompts.
|
|
153
|
+
|
|
154
|
+
`auth` checks the pair against Fastmail and stores it in the keychain (service
|
|
155
|
+
`fastmail-sieve-rules`). Run it again when commands fail with HTTP 401.
|
|
156
|
+
|
|
157
|
+
`fastmail-sieve auth --discover` can look for the cookie for you in the Fastmail
|
|
158
|
+
desktop app and in Safari and Chrome. **It reads data that belongs to other
|
|
159
|
+
apps**: it asks the macOS keychain for the "Fastmail Safe Storage" key and
|
|
160
|
+
decrypts the app's cookie database. It is off by default, needs the `auth`
|
|
161
|
+
extra (`pip install 'fastmail-sieve[auth]'`), and prints what it will read
|
|
162
|
+
before it does.
|
|
163
|
+
|
|
164
|
+
### Where credentials are read from
|
|
165
|
+
|
|
166
|
+
In this order, the first that has them wins:
|
|
167
|
+
|
|
168
|
+
| Source | How |
|
|
169
|
+
|--------|-----|
|
|
170
|
+
| Environment | `FASTMAIL_SIEVE_TOKEN` and `FASTMAIL_SIEVE_COOKIE` |
|
|
171
|
+
| Helper command | `FASTMAIL_SIEVE_CREDENTIAL_COMMAND` prints JSON on stdout |
|
|
172
|
+
| Keychain | what `fastmail-sieve auth` stored |
|
|
173
|
+
|
|
174
|
+
The helper command lets a secret manager supply the pair so that nothing is
|
|
175
|
+
stored by this tool. It is run without a shell (use `sh -c '...'` for a
|
|
176
|
+
pipeline) and must print `{"token": "fma1-…", "cookie": "…"}`, optionally with
|
|
177
|
+
`"api_token"`. For example, `FASTMAIL_SIEVE_CREDENTIAL_COMMAND='op read
|
|
178
|
+
op://Private/fastmail-sieve/json'`. It is read from your environment only,
|
|
179
|
+
never from a file in the repository.
|
|
180
|
+
|
|
181
|
+
**Optional API token for folder lookups.** A read-only Fastmail API token
|
|
182
|
+
(Settings > Privacy & Security > Connected apps & API tokens, Email scope) in
|
|
183
|
+
`FASTMAIL_API_TOKEN` is used for `folders` and the folder checks in `lint`
|
|
184
|
+
instead of the session pair. It cannot read or write the script.
|
|
185
|
+
|
|
186
|
+
There is no command-line option for a token or cookie, because arguments show
|
|
187
|
+
up in `ps` and in shell history. Secrets are never printed: `doctor` and error
|
|
188
|
+
messages name sources and tiers, not values. Without a keychain (headless
|
|
189
|
+
Linux, CI) use environment variables or the helper command. `lint --offline`
|
|
190
|
+
needs no credentials at all, so run that in CI; pushing from CI is not
|
|
191
|
+
recommended.
|
|
192
|
+
|
|
193
|
+
`fastmail-sieve auth status` shows, without contacting Fastmail, each source in
|
|
194
|
+
the order it is tried (environment, helper command, keychain), what it provides
|
|
195
|
+
and whether it is complete, and which credentials each kind of command would
|
|
196
|
+
use: the script needs the session pair, while `folders` prefers an API token.
|
|
197
|
+
It never prints a value, and it reports a failing helper command or a missing
|
|
198
|
+
keychain as a state instead of stopping.
|
|
199
|
+
|
|
200
|
+
`fastmail-sieve doctor` checks the project files, the credentials, what
|
|
201
|
+
Fastmail lets them do (folders, the script, managed blocks) and whether
|
|
202
|
+
Fastmail advertises an official Sieve API, and says what to fix.
|
|
203
|
+
|
|
204
|
+
## Starting a project
|
|
205
|
+
|
|
206
|
+
`fastmail-sieve init` creates `rules/top.sieve`, `rules/middle.sieve`,
|
|
207
|
+
`rules/bottom.sieve`, `variables.toml` and a `.gitignore` entry, and never
|
|
208
|
+
overwrites a file. Run `fastmail-sieve init --remote` once to add the three
|
|
209
|
+
managed blocks to Fastmail's script if it has none yet (a one-time write that
|
|
210
|
+
keeps any code already there), then `fastmail-sieve pull`. Commands find the
|
|
211
|
+
project from any subdirectory, or use `-C DIR`. An optional
|
|
212
|
+
`fastmail-sieve.toml` in the project root can set `rules-dir` and
|
|
213
|
+
`variables-file`.
|
|
214
|
+
|
|
215
|
+
## Reading `explain`
|
|
216
|
+
|
|
217
|
+
Rules are numbered in the order they run: your `top` and `middle` rules, then
|
|
218
|
+
Fastmail's UI rules, then your `bottom` rules. Each section has its own
|
|
219
|
+
heading. Output is coloured on a terminal; `NO_COLOR=1` or `--color never`
|
|
220
|
+
turns it off, and `--width N` sets the table width.
|
|
221
|
+
|
|
222
|
+
| Marker | Meaning |
|
|
223
|
+
|--------|---------|
|
|
224
|
+
| 📌 | Pin (flag) the message |
|
|
225
|
+
| 📁 | Move: file into a folder and stop |
|
|
226
|
+
| 🔖 | Label: copy into a folder and keep going |
|
|
227
|
+
| 🚮 | Trash |
|
|
228
|
+
| 🚫 | Junk / spam |
|
|
229
|
+
| 🛑 | Stop applying further rules |
|
|
230
|
+
| ❗ | Duplicate UI rule, or your rule overlaps a UI rule |
|
|
231
|
+
|
|
232
|
+
In conditions the wording is dim and the values being matched (addresses,
|
|
233
|
+
domains, subjects) are shown at normal brightness; with `explain script`,
|
|
234
|
+
Fastmail's own rules are dim throughout. Variable wording comes from `variables.toml`.
|
|
235
|
+
|
|
236
|
+
## Folder ids and names
|
|
237
|
+
|
|
238
|
+
Rules file mail with `fileinto :mailboxid "ID" "name"`. The id is what Fastmail
|
|
239
|
+
uses and it survives a folder rename; the name is only a hint, but it has to
|
|
240
|
+
be right for `lint` to pass. In Sieve the name is the folder's path with `.`
|
|
241
|
+
separators and an `INBOX.` prefix: `INBOX.finance.taxes`, and
|
|
242
|
+
`INBOX.Inbox.Shopping` for a folder inside the Inbox. `fastmail-sieve lint --fix`
|
|
243
|
+
writes them that way, and `lint` compares them with the live folders. Look ids
|
|
244
|
+
up with `fastmail-sieve folders`.
|
|
245
|
+
|
|
246
|
+
## Migrating a UI rule to a custom rule
|
|
247
|
+
|
|
248
|
+
1. Run `fastmail-sieve migrate` and review the output. It supports UI rules
|
|
249
|
+
that match plain `from` searches and file into one folder, optionally
|
|
250
|
+
skipping the Inbox, pinning and stopping. Anything else is an error
|
|
251
|
+
naming the rule and the reason.
|
|
252
|
+
2. Paste the rules into a block of `rules/middle.sieve`, then run
|
|
253
|
+
`fastmail-sieve lint --fix`.
|
|
254
|
+
3. `fastmail-sieve diff`, then `fastmail-sieve push`.
|
|
255
|
+
4. Disable or delete the UI rule in Fastmail. Until you do, `explain` and
|
|
256
|
+
`lint` flag the overlap.
|
|
257
|
+
|
|
258
|
+
A search that isn't a plain `from` address becomes a `jmapquery` rule that
|
|
259
|
+
reuses the UI rule's exact search, so it matches what the UI rule matches. This
|
|
260
|
+
is the only way to express a contact-card rule. Short searches are one quoted
|
|
261
|
+
line; long ones use a multi-line `text:` block, whose closing `.` must start at
|
|
262
|
+
column 0. Only things with no translation (for example a variable other than
|
|
263
|
+
skip-inbox, pin or stop, or several folders in one rule) are errors.
|
|
264
|
+
|
|
265
|
+
Translation differences: `from:x` in a UI rule is a text search (it also
|
|
266
|
+
matches display names and substrings), while the custom rule matches the
|
|
267
|
+
address exactly (`:domain` for bare domains). Test a sample message in
|
|
268
|
+
Fastmail's Sieve tester.
|
|
269
|
+
|
|
270
|
+
## Using it in CI or a pre-commit hook
|
|
271
|
+
|
|
272
|
+
`fastmail-sieve lint --offline` (add `--fix` for a pre-commit hook) needs no
|
|
273
|
+
credentials and no network. Everything else talks to Fastmail with a full web
|
|
274
|
+
session, so keep it out of CI (see [Credentials](#credentials)).
|
|
275
|
+
|
|
276
|
+
## Development
|
|
277
|
+
|
|
278
|
+
```sh
|
|
279
|
+
uv sync --all-extras
|
|
280
|
+
uv run python -m unittest discover -s tests -t .
|
|
281
|
+
mise run lint # every check, via hk
|
|
282
|
+
mise run package-check # build, twine check, install the wheel in a clean env
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Versions come from git tags (`hatch-vcs`), and releases are published to PyPI
|
|
286
|
+
by trusted publishing from CI. The Python is a library of small modules under
|
|
287
|
+
`src/fastmail_sieve/` with one small module per command in `commands/`;
|
|
288
|
+
library code never prints or exits.
|
|
289
|
+
|
|
290
|
+
## Relationship to Fastmail-Sieve-Sync
|
|
291
|
+
|
|
292
|
+
[Fastmail-Sieve-Sync](https://github.com/fuyu0425/Fastmail-Sieve-Sync) (MIT,
|
|
293
|
+
by Yu-Fu Fu) keeps the managed blocks of your Fastmail Sieve script in sync
|
|
294
|
+
with a file. It is where this project learned that the private `SieveBlocks`
|
|
295
|
+
methods exist and what they carry, and it defined the `Managed by Sieve Sync`
|
|
296
|
+
markers around the managed blocks.
|
|
297
|
+
|
|
298
|
+
**What this project takes from it.** The approach (read and write the script
|
|
299
|
+
through `SieveBlocks`), the idea of marking the managed blocks, and the way the
|
|
300
|
+
blocks are handled. That part is reimplemented in this project's own code,
|
|
301
|
+
written from reading Sieve-Sync's source; no source file was copied verbatim.
|
|
302
|
+
Its license and copyright notice are reproduced in [`NOTICE`](NOTICE).
|
|
303
|
+
|
|
304
|
+
**Why a separate tool rather than a dependency or a fork.**
|
|
305
|
+
|
|
306
|
+
- Sieve-Sync is a command-line tool, not a library, and it is not published on
|
|
307
|
+
PyPI. A package on PyPI cannot depend on a git URL, so depending on it meant
|
|
308
|
+
running it as a subprocess: a temporary config file holding your token, its
|
|
309
|
+
debug output to parse, and a scratch file for the script.
|
|
310
|
+
- The checks and the diff here need the script's parts in memory, and
|
|
311
|
+
`push` verifies the result with a fresh read.
|
|
312
|
+
- The scope is wider than syncing: lint, explain, migrate and folder
|
|
313
|
+
validation.
|
|
314
|
+
|
|
315
|
+
**If you only need to sync a file**, Sieve-Sync is smaller and may be all you
|
|
316
|
+
need. A script that Sieve-Sync manages keeps its markers here, so you can
|
|
317
|
+
switch to this tool and back. A script prepared by this tool has its own
|
|
318
|
+
markers, which Sieve-Sync does not recognise, so do not run both tools on the
|
|
319
|
+
same script. This project is not affiliated with Sieve-Sync or its author.
|
|
320
|
+
|
|
321
|
+
## Credits and license
|
|
322
|
+
|
|
323
|
+
Sieve parsing uses [sievelib](https://github.com/tonioo/sievelib). The session
|
|
324
|
+
and method-call flow is standard JMAP
|
|
325
|
+
([RFC 8620](https://www.rfc-editor.org/rfc/rfc8620)). See the previous section
|
|
326
|
+
and [`NOTICE`](NOTICE) for Sieve-Sync.
|
|
327
|
+
|
|
328
|
+
MIT, see `LICENSE` and `NOTICE`. "Fastmail" is a trademark of its owner; this
|
|
329
|
+
project is not affiliated with or endorsed by Fastmail.
|