zohomail-free 0.1.1

Read, send, and reply to Zoho Mail emails on free-tier accounts — no IMAP or POP3 needed

zohomail-free

Built by MelkonTech
Documentation · PyPI · GitHub

Read, send, and reply to Zoho Mail emails from Python or the command line — for free.

Zoho locks IMAP/POP3 behind paid plans, so you can't use standard email libraries on a free account. zohomail-free works around this by authenticating via the Zoho web UI and hitting their internal API directly — giving you full access to your inbox, outbox, and SMTP sending without paying for a plan.

Install

pip install zohomail-free
playwright install chromium

Setup

Copy .env.example to .env and fill in your credentials:

ZOHO_EMAIL=[e-mail]
ZOHO_PASSWORD=your_zoho_login_password
ZOHO_APP_PASSWORD=your_app_specific_password   # for sending
ZOHO_REGION=eu   # eu or com

Generate an app-specific password in Zoho Mail → Settings → Security → App Passwords.

CLI

# list inbox
zohomail list
zohomail list --limit 20 --json

# read a message (get the id from list output)
zohomail read --id 1782000221530004400

# send new email
zohomail send --to [e-mail] --subject "Hello" --body "Hi there"

# reply to an email
zohomail reply --id 1782000221530004400 --body "Thanks!"

Python

import asyncio
from zohomail.client import ZohoMailClient

client = ZohoMailClient(
    email="[e-mail]",
    password="your_password",
    region="eu",
)

# list inbox
emails = asyncio.run(client.list_emails(limit=5))
for e in emails:
    print(e["subject"], "-", e["from"])

# read full email
email = asyncio.run(client.read_email(emails[0]["id"]))
print(email["body"])

Self-hosted API

cp .env.example .env   # fill in credentials + set a strong API_KEY

# with Docker
docker build -t zohomail-free .
docker run -p 8000:8000 --env-file .env zohomail-free

# or directly
pip install git+https://github.com/MelkonTech/zohomail-free.git
zohomail-api

Endpoints

Method	Path	Description
GET	/emails	List inbox (?limit=10)
GET	/emails/{id}	Read full email
POST	/emails/send	Send new email
POST	/emails/{id}/reply	Reply to email
GET	/health	Health check

All endpoints require X-API-Key: <your_key> header (set API_KEY in .env).

curl -H "X-API-Key: your_key" http://localhost:8000/emails

Deploy to Railway

1. Fork this repo on GitHub
2. Go to railway.app → New Project → Deploy from GitHub repo
3. Select your fork
4. Add environment variables from .env.example in Railway's Variables tab
5. Deploy — Railway auto-detects the Dockerfile

How it works

Zoho's free plan blocks IMAP/POP3 with ACCESS_RESTRICTED_BY_ZOHOMAIL. However, their web UI communicates with an internal JSON API (ml.do / md.do) over HTTPS. This library uses Playwright to authenticate once, saves the session cookie, then makes API calls from within the browser context where cookies are correctly scoped — no paid plan required.

Session cookies are cached at ~/.zohomail_session.pkl and reused on subsequent runs. If the session expires, the library automatically re-authenticates.

Documentation

Full docs at melkontech.github.io/zohomail-free

Author

Built by MelkonTech

License

MIT — see LICENSE