mail_connector

Gmail connector for Python — read, modify, and organize emails via OAuth2.

Installation

pip install mes-courriels

Setup

1. Create a Google Cloud project and enable the Gmail API
2. Create an OAuth2 Client ID (type Desktop)
3. Copy .env.example to .env and fill in GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET
4. Run the auth script to get a refresh token:

uv run python scripts/auth.py

Usage

from mail_connector import GmailConnector

gmail = GmailConnector()

gmail.list_labels()
gmail.list_messages(query="from:alice@example.com")
gmail.get_message("msg_id")

gmail.mark_as_read("msg_id")
gmail.mark_as_unread("msg_id")
gmail.archive("msg_id")
gmail.trash("msg_id")
gmail.modify_message("msg_id", add_label_ids=["STARRED"])

gmail.send_message("to@example.com", "Subject", "Body text")

CLI

mes-courriels alice@example.com              # 10 derniers messages
mes-courriels alice@example.com -n 3         # les 3 derniers
mes-courriels alice@example.com -w           # surveiller en continu (60s)
mes-courriels alice@example.com -w -i 30     # surveiller toutes les 30s

Development

• Python >= 3.12, uv

uv sync
uv run pytest