mailsuite

A Python package for retrieving, parsing, and sending emails.

Features

Simplified IMAP client (mailsuite.imap.IMAPClient) — usable on its own, and the engine behind the mailbox abstraction's IMAP backend
- Automatic reconnection and retries after dropped connections and timeouts
- Watch a folder for new messages with IDLE callbacks, including periodic session refresh
- Username/password or OAuth2 (XOAUTH2 / OAUTHBEARER) login
- Always uses / as the folder hierarchy separator, converting to the server's separator and prepending its namespace automatically, and stripping folder-name characters that collide with the separator
- Works around server quirks across Gmail, Microsoft 365, Exchange, Dovecot, and DavMail, including:
  - Gmail / Google Workspace returning an empty IDLE response
  - Random Microsoft 365 / Exchange BAD / "unexpected response" errors
  - Nonstandard hierarchy separators and namespaces
Provider-agnostic mailbox abstraction (mailsuite.mailbox)
- Single MailboxConnection interface for IMAP, Microsoft Graph, Gmail, and on-disk Maildir
- Fetch message identifiers from any folder, retrieve their raw RFC 822 content, and move or delete messages
- Folder management across every backend — create, rename, move, merge, delete, and existence checks, with consistent FolderExistsError / FolderNotFoundError semantics
- Watch a folder for new messages — the IMAP IDLE command on the IMAP backend, polling on the cloud backends
- Unified send_message() on backends that support sending (Microsoft Graph, Gmail) — IMAP and Maildir users send through mailsuite.smtp.send_email
Consistent email parsing (mailsuite.utils)
- Parse RFC 822 messages from a string, bytes, or file path into consistent dictionaries, with HTML bodies also converted to Markdown
- SHA256 hashes of attachments
- Parsed Authentication-Results and DKIM-Signature headers
- Email address parsing into display name, local part, domain, and second-level domain, tolerating noncompliant addresses
- Check whether a message passed DKIM or DMARC as a trusted domain (from_trusted_domain)
- Forward and reverse DNS lookup helpers
- Parse Microsoft Outlook .msg files using msgconvert
Simplified email creation and sending (mailsuite.smtp)
- Easily add attachments, plain text, and HTML
- Optional DKIM signing of outgoing mail
- Uses opportunistic encryption (STARTTLS) with SMTP by default
- Username/password or OAuth2 (XOAUTH2 / OAUTHBEARER) login
DKIM signing and verification (mailsuite.dkim)
- Generate RSA keypairs and the matching DNS TXT record
- Sign outbound mail with a sensible default header set
- Verify one or many DKIM-Signature headers on a received message
ARC (Authenticated Received Chain) sealing and verification (mailsuite.arc)
- Seal forwarded mail with an ARC set, extending an existing chain
- Verify the ARC chain on a received message and read its cv result

Installation

Base install (IMAP, SMTP, DKIM, Maildir, parsing):

pip install mailsuite

If you would like to be able to parse Microsoft Outlook .msg files, install msgconvert. On Debian-based Linux distributions, msgconvert can be installed via sudo apt-get install libemail-outlook-message-perl. Other systems can use cpan -i Email::Outlook::Message.

The Microsoft Graph and Gmail backends are optional extras — the cloud SDKs aren't pulled in unless you ask for them:

pip install "mailsuite[msgraph]"   # Microsoft Graph (msgraph-sdk + azure-identity)
pip install "mailsuite[gmail]"     # Gmail (google-api-python-client + google-auth-oauthlib)
pip install "mailsuite[all]"       # both

Importing mailsuite.mailbox never requires the extras. Referencing MSGraphConnection or GmailConnection without the matching extra installed raises an ImportError pointing at the right install command.

Microsoft Graph notes

MSGraphConnection defaults to the worldwide cloud (https://graph.microsoft.com). To target a sovereign cloud or any other Graph endpoint, pass graph_url:

MSGraphConnection(..., graph_url="https://graph.microsoft.us")

The azure-identity token cache lives under name="mailsuite" by default. Applications migrating from a previous installation that used a different cache name can pass it through token_cache_name= so existing cached AuthenticationRecords and tokens continue to work — for example, token_cache_name="parsedmarc" keeps users authenticated across the migration.

Microsoft Graph permissions

Grant the appropriate Microsoft Graph API permissions on the app registration based on which MSGraphConnection operations you need. Combine permissions across rows when you need multiple capabilities — e.g., to both read and send mail in a delegated flow against your own mailbox, grant Mail.ReadWrite and Mail.Send.

Use case	Delegated (own mailbox)	Delegated (shared mailbox)	App-only
Read messages only (`fetch_message`, `fetch_messages`)	`Mail.Read`	`Mail.Read.Shared`	`Mail.Read`
Read + modify (mark read, delete, move, create folder)	`Mail.ReadWrite`	`Mail.ReadWrite.Shared`	`Mail.ReadWrite`
Send mail (`send_message`)	`Mail.Send`	`Mail.Send.Shared`	`Mail.Send`

Delegated flows (DeviceCode, UsernamePassword) targeting a shared mailbox — i.e. when the mailbox argument differs from username — use the .Shared variants. App-only flows (ClientAssertion, ClientSecret, Certificate) do not need the .Shared variants since application permissions span every mailbox in the tenant (unless restricted by an Application Access Policy).

For delegated flows, MSGraphConnection requests Mail.ReadWrite (or Mail.ReadWrite.Shared) at authenticate time, so even read-only callers must consent to at least Mail.ReadWrite. App-only flows authenticate with https://graph.microsoft.com/.default, which grants whichever permissions the app registration has consented.

Metadata

Release files for mailsuite 2.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mailsuite 2.3.2
File	Size	Uploaded
mailsuite-2.3.2.tar.gz	43.5 kB	Sep 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mailsuite 2.3.2
File	Interpreter	ABI	Platform	Reset
mailsuite-2.3.2-py3-none-any.whl 51.4 kB Sep 12, 2026	Python 3	none	any	Details

Total release size: 94.9 kB

Release files / mailsuite-2.3.2.tar.gz

Download URL	mailsuite-2.3.2.tar.gz
Size	43.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`ff415d2619bebaef77bfdbb2648656f3ae504e65e99fe8e7df3c3201cecec1da`
BLAKE2b-256 checksum How to use checksums	`10932c5c89ca06c0274247d4de076ea73a5476c117b08dc7f31430c8f653faae`
Upload date	Sep 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/seanthegeek/mailsuite
Publishing commit: github.com/seanthegeek/mailsuite/tree/673f7bbb1267ffb36bdf7bdad48442523dffe5c5

Workflow

Publishing configuration: github.com/seanthegeek/mailsuite/blob/673f7bbb1267ffb36bdf7bdad48442523dffe5c5/.github/workflows/release.yml
Publishing logs: github.com/seanthegeek/mailsuite/actions/runs/34709355829/attempts/1

Artifact

Subject: mailsuite-2.3.2.tar.gz
SHA-256 checksum: ff415d2619bebaef77bfdbb2648656f3ae504e65e99fe8e7df3c3201cecec1da Verifying attestations

Release files / mailsuite-2.3.2-py3-none-any.whl

Download URL	mailsuite-2.3.2-py3-none-any.whl
Size	51.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`68369ae666be68a8d17c461cf202d268fc556b28ea116b49e1ca00676a2b6713`
BLAKE2b-256 checksum How to use checksums	`71483d503a53991a07e1f2ec2a3fc91b68f882a15a3d61148106d37c8a470f0b`
Upload date	Sep 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/seanthegeek/mailsuite
Publishing commit: github.com/seanthegeek/mailsuite/tree/673f7bbb1267ffb36bdf7bdad48442523dffe5c5

Workflow

Publishing configuration: github.com/seanthegeek/mailsuite/blob/673f7bbb1267ffb36bdf7bdad48442523dffe5c5/.github/workflows/release.yml
Publishing logs: github.com/seanthegeek/mailsuite/actions/runs/34709355829/attempts/1

Artifact

Subject: mailsuite-2.3.2-py3-none-any.whl
SHA-256 checksum: 68369ae666be68a8d17c461cf202d268fc556b28ea116b49e1ca00676a2b6713 Verifying attestations