imap-rules-1.0.0 is not a library.

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

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.

# 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

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

Scheduling with Ofelia

You can use Ofelia to schedule the rules to run periodically. A complete example is provided in the 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

[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.

imap-rules 1.0.0