Skip to main content

Convenience classes and methods for processing IMAP mailboxes

Project description

Here are some convenience classes and methods for processing IMAP mailboxes. Since the classes are derived from the imaplib classes, all methods available in the imaplib classes are directly usable.


easy_install -U imapIO


# Connect to IMAP server
import imapIO
server = imapIO.connect(host, port, user, password)

# Select folder
import random
emailCount =

# Walk emails in inbox sorted by arrival time
for email in server.walk('inbox', sortCriterion='ARRIVAL'):
    # Show information
    print 'Date: %s' % email.whenUTC
    print 'Subject: %s' % email.subject.encode('utf-8')
    print 'From: %s' % email.fromWhom.encode('utf-8')
    print 'From (nickname): %s' % imapIO.clean_nickname(email.fromWhom)
    print 'To: %s' % email.toWhom.encode('utf-8')
    print 'CC: %s' % email.ccWhom.encode('utf-8')
    print 'BCC: %s' % email.bccWhom.encode('utf-8')
    # Set flags
    email.seen = False
    email.deleted = False

# Walk emails satisfying search criterion
emailCriterion = 'BEFORE 23-JAN-2005'
emailGenerator = server.walk(lambda folder: folder not in ['public', 'trash'], searchCriterion=emailCriterion)
for emailIndex, email in enumerate(emailGenerator):
    # Show flags
    print email.flags
    # Save email in compressed format on hard drive
    emailPath = '%s.gz' % emailIndex
    partPacks =
    # Extract attachments from email on hard drive
    for partIndex, filename, contentType, payload in imapIO.extract(emailPath):
        print len(payload), filename.encode('utf-8')

# Create an email in the inbox
import datetime
server.revive('inbox', imapIO.build_message(
    whenUTC=datetime.datetime(2005, 1, 23, 1, 0),
# Load email
email = server.walk('inbox', searchCriterion='FROM TO').next()
# Browse attachments in email
partPacks = email.extract(
    include=lambda index, name, type: name.lower().endswith('.rst'),
for partIndex, filename, contentType in partPacks:
    print filename
# Delete email
email.deleted = True

# Duplicate an email from one server to another
server1 = imapIO.connect(host1, port1, user1, password1)
server2 = imapIO.connect(host2, port2, user2, password2)
server2.revive('inbox', server1.walk().next())


  • Added examples to _IMAPExtension.walk() docstring

  • Added Email.extract() for getting attachments directly from an email message

  • Cached Email.as_string()

  • Changed error formatting

  • Fixed bug in Email.flags() so it handles messages with no flags

  • Fixed bug in extract() so that it does not try to decode non-text into unicode

  • Modified extract() to filter attachments using a lambda function


  • Modified _IMAPExtension.walk() to accept a generic function to filter folders

  • Modified Email.__init__() to apply _decode() to both parts of an email address

  • Removed clean_tag(), parse_tags, format_tags()

  • Added utf-7-imap4 codec to parse folder names

  • Increased test coverage to 100%


  • Fixed revive() to handle messages that lack a date

  • Modified Email so an email from _IMAPExtension.walk() can be sent to revive()

  • Modified Email so we can access its parent folder

  • Modified flags.setter so that it does not try to set flag “Recent”


  • Reverted to set() for versions of Python < 2.7 that lack set literal syntax

  • Removed keyword arguments from decode() to support versions of Python < 2.7

  • Fixed tests for servers like Lotus Domino that do not update search indices


  • Changed _IMAPExtension.walk() to use UID directly

  • Added support for sortCriterion using UID SORT

  • Improved test coverage to 80%


  • Extracted code from imap-search-scout

  • Made API more user-friendly

  • Improved test coverage to 79%

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

imapIO-0.9.5.tar.gz (10.8 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page