Package: pymap
pymapLightweight, asynchronous IMAP serving in Python.This project attempts to simplify the complexity of theIMAP protocolinto
a set of clean Python APIs that can be implemented by pluggable backends.
Everything runs in anasyncioevent loop.API DocumentationDocker ImageTable of ContentsInstall and Usagedict Pluginmaildir Pluginmaildir Quick Startredis Pluginredis Quick StartAdmin ToolConfiguring an MTASupported ExtensionsDevelopment and TestingType HintingInstall and Usage$pipinstallpymap$pymap--help$pymapdict--help$pymapmaildir--helpdict PluginThe dict plugin uses in-memory dictionary objects to store mail and metadata.
While the server is running, all concurrent and future connections will see the
same data, including added and removed messages, but no changes will persist if
the server is restarted.You can try out the dict plugin with demo data:$pymap--port1143--debugdict--demo-dataIn another terminal, connect to port 1143 and run some commands:* OK [CAPABILITY IMAP4rev1 STARTTLS AUTH=PLAIN AUTH=LOGIN AUTH=CRAM-MD5 BINARY UIDPLUS MULTIAPPEND IDLE APPENDLIMIT=1000000000] Server ready my.hostname.local
. login demouser demopass
. OK Authentication successful.
. select INBOX
* OK [PERMANENTFLAGS (\Answered \Deleted \Draft \Flagged \Seen)] Flags permitted.
* FLAGS (\Answered \Deleted \Draft \Flagged \Recent \Seen)
* 4 EXISTS
* 1 RECENT
* OK [UIDNEXT 105] Predicted next UID.
* OK [UIDVALIDITY 4097774359] UIDs valid.
* OK [UNSEEN 4] First unseen message.
. OK [READ-WRITE] Selected mailbox.
. logout
* BYE Logging out.
. OK Logout successful.Here are some other commands to try:. uid fetch 1:* all
. list "" *
. create "A New Folder"
. store * +FLAGS (\Deleted)
. expungeAdd new messages using the append command:. append INBOX (\Flagged) {38+}
From: user@example.com

test message!maildir PluginThe maildir plugin uses on-disk storage for mail and metadata. For mail data,
it uses the eponymousMaildirformat. However, since Maildir alone is not
enough for modern IMAP usage, it is extended with additional data as described
in Dovecot'sMailboxFormat/Maildir, with the intention of being fully
compatible.For login, the plugin uses files compatible with the/etc/passwd,/etc/shadow, and/etc/groupformats. By default, they are
prefixed withpymap-etc-and placed inside the configured base directory to
avoid conflicting with the corresponding system files.maildir Quick StartStart the pymap server pointing to a base directory, e.g.:$pymap--port1143--debugmaildir~/maildir/In another terminal, usepymap-adminto create a user to login
with:$pymap-adminset-userdemouser#Typeinapasswordattheprompt,e.g."demopass"If you already have a maildir folder that you could like to reuse, you can
re-assign your user'smailbox_path:$pymap-adminset-user--parammailbox_path=/path/to/mailboxdemouser#Re-typeorchangethepasswordYou are now ready to login to IMAP on port 1143 using your favorite mail
client.redis PluginThe redis plugin uses theRedisdata structure store for mail and
metadata. It requiresredis-pyand will not appear in the plugins list
without it.$pipinstall'pymap[redis]'$pymapredis--helpKeys are composed of a heirarchy of prefixes separated by/. For example, the
key containing the flags of a message might be:/ns/eacb1cf1558741d0b5419b3f838882f5/mbx/Fdaddd3075d7b42e78a7edb1d87ee5800/msg/9173/flagsIn this example, theeacb1cf1558741d0b5419b3f838882f5andFdaddd3075d7b42e78a7edb1d87ee5800prefixes are randomly generated IDs acting
as the namespaces for the login user and mailbox, respectively, and the message
has UID9173.redis Quick StartStart the pymap server pointing to a local redis server, or use--addressto
connect to a remote redis, e.g.:$pymap--port1143--debugredis# --address redis://my.redisIn another terminal, usepymap-adminto create a user to login
with:$pymap-adminset-userdemouser#Typeinapasswordattheprompt,e.g."demopass"You are now ready to login to IMAP on port 1143 using your favorite mail
client.Admin ToolWith optional dependencies, the pymap server will also open agRPCservice providing administrative operations for the running server.$pipinstall'pymap[admin,macaroon]'The admin service can create, update, and delete users, deliver new messages,
check credentials, and provide health checks.Thepymap-adminCLI tool simplifies interacting with the admin service.
It can also be installed standalone to interact with remote pymap servers:$pipinstallpymap-admin$pymap-admin--helpConfiguring an MTAThe admin tool can be used as a"local delivery agent"for an MTA with
theappendsub-command. For example, in postfix you might use:mailbox_command = /some/where/pymap-admin --from "$SENDER" "$USER"This setup may be combined withremote authenticationto keep a clean
separation between your MTA and pymap.Supported ExtensionsIn addition toRFC 3501, pymap supports a number of IMAP extensions to
give clients easier and more powerful use.RFC 2177Adds theIDLEcapability and command, which lets clients wait (without
issuing commands) and receive mailbox updates as they happen without polling.RFC 2180Defines some conventions for handling multi-access in scenarios such asEXPUNGEand mailbox deletion.RFC 2971Adds theIDcapability and command, which lets clients send and receive
arbitrary information for "statistical" purposes and bug reports.RFC 3502Adds theMULTIAPPENDcapability, allowing multiple messages to be atomically
appended to a mailbox with a singleAPPENDcommand.RFC 3516Adds theBINARYextension, providing better support for the encoding and
transfer of binary data.RFC 4315Adds theUIDPLUScapability, which adds theUID EXPUNGEcommand and defines
theAPPENDUIDandCOPYUIDgiving clients more insight into the messages
added to a mailbox.RFC 4466No additional functionality by itself, but allows pymap to be extended easily
and more robustly handle bad client implementations.RFC 5530Adds additional IMAP response codes that can help tell an IMAP client why a
command failed.RFC 7889 (partial)Adds theAPPENDLIMIT=capability, declaring the maximum message size a server
will accept from anAPPENDcommand. Mailbox-specific limitations defined
by the RFC are not supported.RFC 8474Adds theOBJECTIDcapability, assigning unique IDs to mailboxes, messages,
and threads to improve client caching and display.Development and TestingYou will need to do some additional setup to develop and test plugins. InstallHatchto use the CLI examples below.Run all tests and linters:$hatchruncheckType HintingThis project makes heavy use of Python'stype hintingsystem, with the
intention of a clean run ofmypy.No code contribution will be accepted unless it makes every effort to use type
hinting to the extent possible and common in the rest of the codebase.