imap-rules 1.0.0

A utility for running rules against an IMAP server
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

# IMAP rules

This is a command-line utility that can run simple rules against an IMAP server.
Run it as a once-off, or schedule it to run more frequently.

## Usage

```shell
imap-rules --help                           # Show usage instructions
imap-rules rules.toml --dry-run             # Describe what would happen
imap-rules rules.toml --describe            # List all folders and flags
imap-rules rules.toml --rule-name inbox     # Run only a specific rule
imap-rules rules.toml                       # Actually run
```

## Docker

You can also run `imap-rules` as a Docker container using the image `codeberg.org/cascer1/imap-rules`.

To run the container, you need to mount your `rules.toml` file into the container.

```shell
# Dry run
docker run --rm -v ./rules.toml:/rules.toml codeberg.org/cascer1/imap-rules /rules.toml --dry-run

# Actually run
docker run --rm -v ./rules.toml:/rules.toml codeberg.org/cascer1/imap-rules /rules.toml
```

## Scheduling with cron

```crontab
0 */6 * * * /path/to/imap-rules /path/to/rules
```

## Scheduling with Ofelia

You can use [Ofelia](https://github.com/mcuadros/ofelia) to schedule the rules to run periodically. 
A complete example is provided in the [examples](examples) directory.

This will start a scheduler that runs the rules once a day. 

## How does it work?

The program reads your config file which contains any number of rules.
These rules contain filters (folder, min age, read status) and action (delete, move, purge)

## What do rules look like?

Rules describe what messages they should search for, and what should happen with them. Rules can move messages to trash
or any other folder.

Rules have the following properties:

| Property          | description                                          | default                        |
|-------------------|------------------------------------------------------|--------------------------------|
| `path`            | IMAP folder name                                     | *required*                     |
| `min_age`         | Only affect messages older than given number of days | *required*                     |
| `include_unread`  | Also affect unread messages                          | `false`                        |
| `include_flagged` | Also affect flagged messages                         | `false`                        |
| `action`          | What to do with the message                          | *required*                     |
| `move_target`     | Where to move the message if action is `move`        | *required* if action is `move` |

**actions**

* `move` - Move the messages to the folder in `move_target`
* `trash` - Move messages to the trash folder
* `purge` - Permanently delete messages

### Examples

```toml
[rules]
[rules.inbox]
path = "Inbox"          # Search inbox for messages
min_age = "28d"         # Only messages older than 28 days
include_unread = false  # Only read messages
action = "move"         # Move to a different folder
move_target = "Archive.auto_expire"  # Move to this folder

[rules.auto_archive]
path = "Archive.auto_expire"
min_age = "180d"        # Only include messages older than 180 days
include_unread = true   # Also include unread messages
action = "trash"        # Move messages to trash

[rules.cleanup_spam]
path = "Junk"
min_age = "30d"
include_unread = true
action = "purge"        # Permanently delete messages
```

Here you can see that you can combine rules by moving messages between folders. In the example, we move all read
messages from the inbox to `Archive/auto_expire` after 28 days. Then messages in that folder are deleted after 180 days.