Metadata-Version: 2.4
Name: matimo-gmail
Version: 0.1.0a14.post1
Summary: Matimo provider — Gmail tools (send, list, read, delete emails)
License: MIT
Keywords: agents,ai,gmail,matimo,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Requires-Dist: matimo-core<0.2.0,>=0.1.0a14.post1
Description-Content-Type: text/markdown

# matimo-gmail

> Gmail tools for [Matimo](https://matimo.dev) — send, list, read, and delete emails.

[![PyPI](https://img.shields.io/pypi/v/matimo-gmail)](https://pypi.org/project/matimo-gmail/)
[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)

---

## Installation

```bash
pip install matimo matimo-gmail
```

---

## Available Tools (6 Total)

| Tool | Description |
|------|-------------|
| `send-email` | Send an email (to, subject, body, cc, bcc, html) |
| `list-messages` | List messages with optional query/label filters |
| `get-message` | Get full message content by ID |
| `create-draft` | Create a draft email |
| `delete-message` | Move message to trash |

---

## Quick Start

```python
import asyncio
from matimo import Matimo
from matimo_gmail import get_tools_path

async def main():
    matimo = await Matimo.init(get_tools_path())

    # Send an email
    await matimo.execute('send-email', {
        'to': 'user@example.com',
        'subject': 'Hello from Matimo',
        'body': 'This message was sent by an AI agent.',
    })

    # List recent messages
    result = await matimo.execute('list-messages', {
        'query': 'is:unread',
        'max_results': 10,
    })

asyncio.run(main())
```

---

## Authentication

Gmail tools use OAuth2. Set your credentials via environment variables:

```bash
export GMAIL_ACCESS_TOKEN="ya29.your-oauth2-access-token"
# Or use a service account
export GMAIL_SERVICE_ACCOUNT_JSON="/path/to/service-account.json"
```

### Getting an Access Token (OAuth2)

1. Create a project in [Google Cloud Console](https://console.cloud.google.com/)
2. Enable the **Gmail API**
3. Create OAuth 2.0 credentials (Desktop app)
4. Run the OAuth flow to get an access token

---

## Documentation

- [Gmail API Reference](https://developers.google.com/gmail/api/reference/rest)
- [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/native/gmail)

---

## Links

- **PyPI:** https://pypi.org/project/matimo-gmail/
- **GitHub:** https://github.com/tallclub/matimo
- **Gmail API Docs:** https://developers.google.com/gmail/api

