Metadata-Version: 2.4
Name: teamver-mail-agent
Version: 0.3.1
Summary: Teamver Mail BE client for AI agent runtimes (inbox, events, processing, reply)
Project-URL: Homepage, https://teamver.com
Project-URL: Documentation, https://github.com/NeuralStudioKr/teamver-sdk-docs/tree/main/mail-agent
Project-URL: Issues, https://github.com/NeuralStudioKr/teamver-sdk-docs/issues
Project-URL: Changelog, https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/mail-agent/changelog.md
Author-email: NeuralStudio <dev@neuralstudio.kr>
Maintainer-email: NeuralStudio <dev@neuralstudio.kr>
License: MIT
License-File: LICENSE
Keywords: agent,async,mail,sdk,teamver
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx<0.28,>=0.27.0
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: teamver-sdk-core>=0.1.1
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# teamver-mail-agent

Async Python client for the **Teamver Mail BE** Agent API (`/v1/agent/*`).  
Built for agents, Hermes, and other AI agent runtimes.

## Install

```bash
pip install teamver-mail-agent
```

Depends on `teamver-sdk-core`. Python **≥ 3.11**.

For the unified agent facade (channel + DM + Drive + mail), install
[`teamver-agent-sdk`](https://pypi.org/project/teamver-agent-sdk/) instead.

## Quick start

```python
import asyncio
from teamver_mail_agent import TeamverMailAgentClient

async def main():
    async with TeamverMailAgentClient.from_env() as client:
        events = await client.list_events(limit=10)
        for ev in events.events:
            if ev.message_id:
                await client.ack_event(ev.event_id)
                msg = await client.get_message(ev.message_id)
                print(msg.subject, msg.body_text)

asyncio.run(main())
```

## Environment

| Field | Env | Description | Default |
|-------|-----|-------------|---------|
| `api_base_url` | `TEAMVER_MAIL_API_BASE` or `TEAMVER_MAIL_API_BASE_URL` | Mail host, **no** `/v1` | `https://mail-api.teamver.com` |
| `agent_token` | `TEAMVER_MAIL_AGENT_TOKEN` | Bearer `tv_agent_…` | *(required)* |
| `internal_api_key` | `TEAMVER_INTERNAL_API_KEY` | Optional — M2M provisioning only | — |

## Scopes

`agent:read`, `agent:events`, `agent:reply` — issued with the mail agent token.

## Recommended loop

```text
list/stream events → ack → get_message → processing_start
→ handle → reply (Idempotency-Key) → processing_complete
```

## Documentation

Public docs: [github.com/NeuralStudioKr/teamver-sdk-docs/tree/main/mail-agent](https://github.com/NeuralStudioKr/teamver-sdk-docs/tree/main/mail-agent)

- [Installation](https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/mail-agent/installation.md)
- [Quick start](https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/mail-agent/quickstart.md)
- [API reference](https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/mail-agent/api-reference.md)
- [Changelog](https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/mail-agent/changelog.md)

## License

MIT — see [LICENSE](./LICENSE).
