Metadata-Version: 2.4
Name: imap-mailbox
Version: 0.3.0
Summary: mailbox over IMAP
Author: Pedro Rodrigues
Author-email: Pedro Rodrigues <medecau@gmail.com>
License-Expression: MIT
Requires-Python: >=3.11
Project-URL: Documentation, https://medecau.github.io/imap_mailbox/
Project-URL: Homepage, https://medecau.github.io/imap_mailbox/
Project-URL: Repository, https://github.com/medecau/imap_mailbox
Description-Content-Type: text/markdown

*Please note that `imap_mailbox` is still under active development and will be subject to significant changes.*

```python
import imap_mailbox

# connect to the IMAP server
with imap_mailbox.IMAPMailbox('imap.example.com', 'username', 'password') as mailbox:
    
    # search messages from vip@example.com
    uids = mailbox.search('FROM', 'vip@example.com')
    
    # move the messages to the 'VIP' folder
    mailbox.move(uids, 'VIP')
```

This module provides a subclass of `mailbox.Mailbox` that allows you to interact with an IMAP server. It is designed to be a drop-in replacement for the standard library `mailbox` module.

# Installation

Install the latest stable version from PyPI:

```bash
pip install imap-mailbox
```

# Examples

## Iterate over messages in a folder

```python
import imap_mailbox

# connect to the IMAP server
with imap_mailbox.IMAPMailbox('imap.example.com', 'username', 'password') as mailbox:
    
    # select the INBOX folder
    mailbox.select('INBOX')
    
    # iterate over messages in the folder
    for message in mailbox:
        print(f"From: {message['From']}")
        print(f"Subject: {message['Subject']}")
```

## Connect to a Proton Mail account

```python
import imap_mailbox

# connect to the local IMAP bridge
with imap_mailbox.IMAPMailbox(
    '127.0.0.1', 'username', 'password'
    port=1143, security='STARTTLS'
    ) as mailbox:
    
    # search messages from your friend
    uids = mailbox.search('FROM', 'tr3nton@proton.me')

    # erase the evidence
    mailbox.delete(uids)
    
```

## Delete messages from a noisy sender

```python
import imap_mailbox

with imap_mailbox.IMAPMailbox('imap.example.com', 'username', 'password') as mailbox:
    
    # search messages from
    uids = mailbox.search('FROM', 'spammer@example.com')

    # delete the messages
    mailbox.delete(uids)
```

## Delete GitHub messages older than two years

```python
import imap_mailbox

with imap_mailbox.IMAPMailbox('imap.example.com', 'username', 'password') as mailbox:
    
    # search messages older than two years from github.com
    uids = mailbox.search('NOT PAST2YEARS FROM github.com')
    
    # delete the messages
    mailbox.delete(uids)
```

# Development

Set up the development environment with dependencies and git hooks:

```bash
./scripts/init-dev.sh
```

# Contribution

Help improve imap_mailbox by reporting any issues or suggestions on our issue tracker at [github.com/medecau/imap_mailbox/issues](https://github.com/medecau/imap_mailbox/issues).

Get involved with the development, check out the source code at [github.com/medecau/imap_mailbox](https://github.com/medecau/imap_mailbox).
