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

Project links

Data verified by PyPI on Aug 18, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Sean.Whalen from gravatar.com Sean.Whalen

Credits

Author: Sean Whalen

GitHub Statistics

Data verified by PyPI on Aug 18, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Provides Extra

all gmail msgraph

Tags

IMAP SMTP email

Classifiers

Report project as malware

Download files

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

Source Distribution

mailsuite-2.3.1.tar.gz (43.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mailsuite-2.3.1-py3-none-any.whl (51.4 kB view details)

Uploaded Python 3

File details

Details for the file mailsuite-2.3.1.tar.gz.

File metadata

  • Download URL: mailsuite-2.3.1.tar.gz
  • Upload date:
  • Size: 43.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mailsuite-2.3.1.tar.gz
Algorithm Hash digest
SHA256 5dce87cf3f463492a76d41fec5ac148b8b19a62078dec168a8dd7587e55acb27
MD5 975c29db40b183cba16fbb4904066ac9
BLAKE2b-256 67261541682687781c85f8eac157847671bbfaf2a1abc581c534879bbec56538

See more details on using hashes here.

Provenance

The following attestation bundles were made for mailsuite-2.3.1.tar.gz:

Publisher: release.yml on seanthegeek/mailsuite

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mailsuite-2.3.1-py3-none-any.whl.

File metadata

  • Download URL: mailsuite-2.3.1-py3-none-any.whl
  • Upload date:
  • Size: 51.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mailsuite-2.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 08e81ba60ce8f25d2b536f8bdd3d25538d3d15b62f4c7fcec15f1c68193cfdb2
MD5 6a5f7690d0d96566a9e642f4cacf8ccb
BLAKE2b-256 ddf05870d4880277eaccecdeaaedcb9bfe7f31270ee1111631cd0b0c77dbe7ca

See more details on using hashes here.

Provenance

The following attestation bundles were made for mailsuite-2.3.1-py3-none-any.whl:

Publisher: release.yml on seanthegeek/mailsuite

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

2.3.1 This release

2 files

2.3.0

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.0

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

1.11.2

2 files

1.11.1

2 files

1.11.0

2 files

1.10.1

2 files

1.10.0

2 files

1.9.20

2 files

Yanked

1.9.19

2 files

Yanked reason: Typo broke mail parsing

1.9.18

2 files

1.9.17

2 files

1.9.16

2 files

1.9.15

2 files

1.9.14

2 files

1.9.13

2 files

1.9.12

2 files

1.9.11

2 files

1.9.9

2 files

1.9.8

2 files

1.9.7

2 files

1.9.6

2 files

1.9.5

2 files

1.9.4

2 files

1.9.3

2 files

1.9.2

2 files

1.9.1

2 files

1.9.0

2 files

1.8.2

2 files

1.8.1

2 files

1.8.0

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.1

2 files

1.6.0

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.4.0

2 files

1.3.1

2 files

1.3.0

2 files

1.2.1

2 files

1.2.0

2 files

1.1.1

2 files

1.1.0

2 files

1.0.0

2 files

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