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

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:

pip install imap-mailbox

Examples

Iterate over messages in a folder

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

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

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

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:

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

Get involved with the development, check out the source code at github.com/medecau/imap_mailbox.