protonlite

A small, dependency-light Python client and API for Proton Mail (ProtonMail) -- Mail, Calendar, Contacts and Drive, with no Proton Mail Bridge and no paid plan. Ships an optional MCP server so an agent (Claude Code, Cursor) can use your mailbox.

Proton has no IMAP or SMTP. The official way in is Proton Mail Bridge, which needs a paid plan. protonlite talks to Proton's web API directly, so it works on a free account, and the end-to-end crypto is ported from Proton's own MIT-licensed Go libraries (go-srp, go-proton-api). It stays MIT-licensed and dependency-light: just OpenPGP (PGPy13, a maintained fork of PGPy), bcrypt and requests. No CAPTCHA solver, no computer-vision stack -- a person completes Proton's verification page the same way Proton's own apps do.

Unofficial. This project is not affiliated with, endorsed by, or supported by Proton AG. "Proton", "Proton Mail", "Proton Calendar" and "Proton Drive" are trademarks of Proton AG. It talks to a private, undocumented API that can change at any time, and using it may be subject to Proton's terms of service. Use it at your own risk, on accounts you own.

What it does

• Mail -- read the inbox and any folder, decrypt messages (HTML flattened to text), search, send (plain or HTML, attachments, replies in-thread, scheduled), save drafts, mark read/unread, trash/delete, labels and folders, empty trash, storage usage.
• Calendar -- read the agenda, create / edit / cancel events, send invitations, RSVP.
• Contacts -- read, create, edit and delete contacts (signed/encrypted vCards).
• Drive -- list, download, upload (encrypted), move, rename, trash, and create public share links.

All of it is end-to-end: keys are unlocked locally with the account password and messages, events, contacts and files are decrypted on your machine.

Install

pip install protonlite

Requires Python 3.10+.

Quickstart

import os
import datetime as dt

from protonlite import ProtonMail

# --- Signing in -------------------------------------------------------------
# The recommended way is the CLI `protonlite login`, which reads the password
# with getpass so it never lives in a script. For automation, read it from the
# environment rather than hard-coding it. Proton usually asks a human to
# complete a verification page; login raises HumanVerificationRequired with
# that URL -- open it, then call again passing verification_token (see
# "Signing in" below). Sign in each account once; every login saves its own
# session file.
ProtonMail.login(
    "you@proton.me",
    password=os.environ["PROTON_PASSWORD"].encode(),
    session_path="you@proton.me.json",
)

# --- More than one account --------------------------------------------------
# Reopen each saved session independently -- no password needed. The two
# clients are fully independent mailboxes.
client  = ProtonMail.from_session(session_path="you@proton.me.json")    # personal
client1 = ProtonMail.from_session(session_path="work@proton.me.json")   # work
# (after a CLI `protonlite login`, ProtonMail.for_account("work") finds it by name)
print(client.addresses()[0]["Email"], "/", client1.addresses()[0]["Email"])

# --- Mail -------------------------------------------------------------------
for msg in client.list_messages(unread_only=True):
    print(msg.time, msg.sender.address, msg.subject)
full = client.read_message(msg.id)
print(full.text)                                  # HTML flattened to prose
client.send(to=["friend@example.com"], subject="Hi", body="Hello")
client1.send(to=["teammate@work.com"], subject="Hi from work", body="Hello")

# --- Calendar ---------------------------------------------------------------
cal_id = client.list_calendars()[0]["ID"]
begins = dt.datetime.now(dt.timezone.utc) + dt.timedelt

... [View full README on GitHub](https://github.com/maytrella007/protonlite#readme)