Skip to main content

mailsuite

PyPI PyPI - Downloads

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
    • Upgrades plain-text connections with STARTTLS, and refuses to authenticate without it unless explicitly allowed with starttls=False
    • 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
    • Upgrades plain-text SMTP connections with STARTTLS, and refuses to send credentials without it unless explicitly allowed with starttls=False
    • 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.6

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.6
File Size Uploaded Provenance Actions
mailsuite-2.3.6.tar.gz 51.1 kB With provenance Details for mailsuite-2.3.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mailsuite 2.3.6
File Interpreter ABI Platform Actions
mailsuite-2.3.6-py3-none-any.whl Python 3 none any Details for mailsuite-2.3.6-py3-none-any.whl

Total release size: 110.5 kB

Release files / mailsuite-2.3.6.tar.gz

Download URL mailsuite-2.3.6.tar.gz
Size 51.1 kB
Tags Source
SHA-256 checksum
How to use checksums
fe91357edbd16f8bf67052d6bdd5ed480c362ab63ef94c3a5dd91f9637c82d26
BLAKE2b-256 checksum
How to use checksums
c67919533c5a7d99f2d5ff02881b8ff1362e046b3e23dbfb2cced306aec961bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

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

Download URL mailsuite-2.3.6-py3-none-any.whl
Size 59.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
731d3c4719adf69cc412ddc4baff46ea521dcdcc417ed29f5120feecea78cb95
BLAKE2b-256 checksum
How to use checksums
655ff40c3190530a7f0f3d6a215825ee8988d7bed6bf13d58370476c029bd47b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for mailsuite 2.3.6

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mailsuite-2.3.6.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.3.6 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page