# mail_connector

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

## Installation

```bash
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:

```bash
uv run python scripts/auth.py
```

## Usage

```python
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

```bash
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](https://docs.astral.sh/uv/)

```bash
uv sync
uv run pytest
```
