mails-agent 1.4.0b1__py3-none-any.whl

mails_agent/__init__.py

@@ -0,0 +1,18 @@
+"""mails-agent — Python SDK for email capabilities for AI agents."""
+
+from .client import AsyncMailsClient, MailsClient
+from .exceptions import ApiError, AuthError, MailsError, NotFoundError
+from .models import Email, SendResult, VerificationCode
+
+__version__ = "1.4.0b1"
+__all__ = [
+    "MailsClient",
+    "AsyncMailsClient",
+    "Email",
+    "SendResult",
+    "VerificationCode",
+    "MailsError",
+    "AuthError",
+    "NotFoundError",
+    "ApiError",
+]

mails_agent/client.py

@@ -0,0 +1,408 @@
+"""Synchronous and asynchronous HTTP clients for the mails-agent API."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+import httpx
+
+from .exceptions import ApiError, AuthError, NotFoundError
+from .models import Email, SendResult, VerificationCode
+
+
+def _parse_email(data: Dict[str, Any]) -> Email:
+    """Convert a raw API dict into an Email dataclass."""
+    return Email(
+        id=data["id"],
+        mailbox=data.get("mailbox", ""),
+        from_address=data.get("from_address", ""),
+        from_name=data.get("from_name", ""),
+        subject=data.get("subject", ""),
+        direction=data.get("direction", "inbound"),
+        status=data.get("status", ""),
+        received_at=data.get("received_at", ""),
+        has_attachments=bool(data.get("has_attachments", False)),
+        attachment_count=int(data.get("attachment_count", 0)),
+        body_text=data.get("body_text", ""),
+        body_html=data.get("body_html", ""),
+        code=data.get("code"),
+    )
+
+
+def _handle_error(response: httpx.Response) -> None:
+    """Raise the appropriate exception for non-2xx responses."""
+    if response.status_code == 401 or response.status_code == 403:
+        raise AuthError(f"Authentication failed ({response.status_code})")
+    if response.status_code == 404:
+        raise NotFoundError("Resource not found")
+    if not response.is_success:
+        try:
+            body = response.json()
+            message = body.get("error", response.reason_phrase)
+        except Exception:
+            message = response.reason_phrase or f"HTTP {response.status_code}"
+        raise ApiError(message, response.status_code)
+
+
+class MailsClient:
+    """Synchronous client for the mails-agent API.
+
+    Args:
+        api_url: Worker API base URL (e.g. ``https://mails-worker.genedai.workers.dev``).
+        token: API key or worker token for authentication.
+        mailbox: Your email address (e.g. ``agent@mails0.com``).
+        timeout: Request timeout in seconds. Defaults to 60 to accommodate
+            long-polling ``wait_for_code`` calls.
+    """
+
+    def __init__(
+        self,
+        api_url: str,
+        token: str,
+        mailbox: str,
+        *,
+        timeout: float = 60.0,
+    ) -> None:
+        self.api_url = api_url.rstrip("/")
+        self.token = token
+        self.mailbox = mailbox
+        self._client = httpx.Client(
+            base_url=self.api_url,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+        )
+
+    # ------------------------------------------------------------------
+    # Context manager support
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "MailsClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def send(
+        self,
+        to: Union[str, List[str]],
+        subject: str,
+        *,
+        text: Optional[str] = None,
+        html: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        attachments: Optional[Sequence[Dict[str, Any]]] = None,
+    ) -> SendResult:
+        """Send an email.
+
+        Args:
+            to: Recipient address or list of addresses.
+            subject: Email subject line.
+            text: Plain-text body.
+            html: HTML body.
+            reply_to: Reply-to address.
+            attachments: List of attachment dicts with ``filename``, ``content``,
+                and optionally ``content_type`` / ``content_id``.
+
+        Returns:
+            A :class:`SendResult` with the message id and provider info.
+        """
+        recipients = [to] if isinstance(to, str) else list(to)
+        payload: Dict[str, Any] = {
+            "from": self.mailbox,
+            "to": recipients,
+            "subject": subject,
+        }
+        if text is not None:
+            payload["text"] = text
+        if html is not None:
+            payload["html"] = html
+        if reply_to is not None:
+            payload["reply_to"] = reply_to
+        if attachments:
+            payload["attachments"] = list(attachments)
+
+        response = self._client.post("/api/send", json=payload)
+        _handle_error(response)
+        data = response.json()
+        return SendResult(
+            id=data["id"],
+            provider=data.get("provider", ""),
+            provider_id=data.get("provider_id"),
+        )
+
+    def get_inbox(
+        self,
+        *,
+        limit: int = 20,
+        offset: int = 0,
+        direction: Optional[str] = None,
+        query: Optional[str] = None,
+    ) -> List[Email]:
+        """Fetch emails from the inbox.
+
+        Args:
+            limit: Maximum number of emails to return.
+            offset: Pagination offset.
+            direction: Filter by ``'inbound'`` or ``'outbound'``.
+            query: Optional search query string.
+
+        Returns:
+            A list of :class:`Email` objects.
+        """
+        params: Dict[str, Any] = {
+            "to": self.mailbox,
+            "limit": limit,
+            "offset": offset,
+        }
+        if direction is not None:
+            params["direction"] = direction
+        if query is not None:
+            params["query"] = query
+
+        response = self._client.get("/api/inbox", params=params)
+        _handle_error(response)
+        data = response.json()
+        return [_parse_email(e) for e in data.get("emails", [])]
+
+    def search(
+        self,
+        query: str,
+        *,
+        limit: int = 20,
+        direction: Optional[str] = None,
+    ) -> List[Email]:
+        """Search emails by query string.
+
+        Args:
+            query: Search query.
+            limit: Maximum number of results.
+            direction: Filter by ``'inbound'`` or ``'outbound'``.
+
+        Returns:
+            A list of matching :class:`Email` objects.
+        """
+        return self.get_inbox(query=query, limit=limit, direction=direction)
+
+    def get_email(self, email_id: str) -> Email:
+        """Fetch a single email by ID.
+
+        Args:
+            email_id: The email's unique identifier.
+
+        Returns:
+            The :class:`Email` object.
+
+        Raises:
+            NotFoundError: If the email does not exist.
+        """
+        response = self._client.get("/api/email", params={"id": email_id})
+        _handle_error(response)
+        return _parse_email(response.json())
+
+    def wait_for_code(
+        self,
+        *,
+        timeout: int = 30,
+    ) -> Optional[VerificationCode]:
+        """Wait for a verification code to arrive.
+
+        This long-polls the server until a code is found or the timeout
+        expires.
+
+        Args:
+            timeout: Maximum seconds to wait. Defaults to 30.
+
+        Returns:
+            A :class:`VerificationCode` if one arrived, or ``None`` on timeout.
+        """
+        # Use a longer HTTP timeout to cover the server-side polling window.
+        response = self._client.get(
+            "/api/code",
+            params={"to": self.mailbox, "timeout": timeout},
+            timeout=max(timeout + 10, 60.0),
+        )
+        _handle_error(response)
+        data = response.json()
+        if not data.get("code"):
+            return None
+        return VerificationCode(
+            code=data["code"],
+            from_address=data.get("from", ""),
+            subject=data.get("subject", ""),
+        )
+
+    def delete_email(self, email_id: str) -> bool:
+        """Delete an email by ID.
+
+        Args:
+            email_id: The email's unique identifier.
+
+        Returns:
+            ``True`` if the email was deleted, ``False`` if it was not found.
+        """
+        response = self._client.delete("/api/email", params={"id": email_id})
+        if response.status_code == 404:
+            return False
+        _handle_error(response)
+        return True
+
+
+# ======================================================================
+# Async client
+# ======================================================================
+
+
+class AsyncMailsClient:
+    """Asynchronous client for the mails-agent API.
+
+    Mirrors :class:`MailsClient` but all methods are ``async``.
+
+    Args:
+        api_url: Worker API base URL.
+        token: API key or worker token for authentication.
+        mailbox: Your email address.
+        timeout: Request timeout in seconds (default 60).
+    """
+
+    def __init__(
+        self,
+        api_url: str,
+        token: str,
+        mailbox: str,
+        *,
+        timeout: float = 60.0,
+    ) -> None:
+        self.api_url = api_url.rstrip("/")
+        self.token = token
+        self.mailbox = mailbox
+        self._client = httpx.AsyncClient(
+            base_url=self.api_url,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+        )
+
+    async def __aenter__(self) -> "AsyncMailsClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def send(
+        self,
+        to: Union[str, List[str]],
+        subject: str,
+        *,
+        text: Optional[str] = None,
+        html: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        attachments: Optional[Sequence[Dict[str, Any]]] = None,
+    ) -> SendResult:
+        """Send an email. See :meth:`MailsClient.send` for details."""
+        recipients = [to] if isinstance(to, str) else list(to)
+        payload: Dict[str, Any] = {
+            "from": self.mailbox,
+            "to": recipients,
+            "subject": subject,
+        }
+        if text is not None:
+            payload["text"] = text
+        if html is not None:
+            payload["html"] = html
+        if reply_to is not None:
+            payload["reply_to"] = reply_to
+        if attachments:
+            payload["attachments"] = list(attachments)
+
+        response = await self._client.post("/api/send", json=payload)
+        _handle_error(response)
+        data = response.json()
+        return SendResult(
+            id=data["id"],
+            provider=data.get("provider", ""),
+            provider_id=data.get("provider_id"),
+        )
+
+    async def get_inbox(
+        self,
+        *,
+        limit: int = 20,
+        offset: int = 0,
+        direction: Optional[str] = None,
+        query: Optional[str] = None,
+    ) -> List[Email]:
+        """Fetch emails from the inbox. See :meth:`MailsClient.get_inbox`."""
+        params: Dict[str, Any] = {
+            "to": self.mailbox,
+            "limit": limit,
+            "offset": offset,
+        }
+        if direction is not None:
+            params["direction"] = direction
+        if query is not None:
+            params["query"] = query
+
+        response = await self._client.get("/api/inbox", params=params)
+        _handle_error(response)
+        data = response.json()
+        return [_parse_email(e) for e in data.get("emails", [])]
+
+    async def search(
+        self,
+        query: str,
+        *,
+        limit: int = 20,
+        direction: Optional[str] = None,
+    ) -> List[Email]:
+        """Search emails by query. See :meth:`MailsClient.search`."""
+        return await self.get_inbox(query=query, limit=limit, direction=direction)
+
+    async def get_email(self, email_id: str) -> Email:
+        """Fetch a single email by ID. See :meth:`MailsClient.get_email`."""
+        response = await self._client.get("/api/email", params={"id": email_id})
+        _handle_error(response)
+        return _parse_email(response.json())
+
+    async def wait_for_code(
+        self,
+        *,
+        timeout: int = 30,
+    ) -> Optional[VerificationCode]:
+        """Wait for a verification code. See :meth:`MailsClient.wait_for_code`."""
+        response = await self._client.get(
+            "/api/code",
+            params={"to": self.mailbox, "timeout": timeout},
+            timeout=max(timeout + 10, 60.0),
+        )
+        _handle_error(response)
+        data = response.json()
+        if not data.get("code"):
+            return None
+        return VerificationCode(
+            code=data["code"],
+            from_address=data.get("from", ""),
+            subject=data.get("subject", ""),
+        )
+
+    async def delete_email(self, email_id: str) -> bool:
+        """Delete an email by ID. See :meth:`MailsClient.delete_email`."""
+        response = await self._client.delete("/api/email", params={"id": email_id})
+        if response.status_code == 404:
+            return False
+        _handle_error(response)
+        return True

mails_agent/exceptions.py

@@ -0,0 +1,27 @@
+"""Custom exceptions for the mails-agent SDK."""
+
+
+class MailsError(Exception):
+    """Base exception for mails-agent SDK."""
+
+    pass
+
+
+class AuthError(MailsError):
+    """Authentication failed (HTTP 401/403)."""
+
+    pass
+
+
+class NotFoundError(MailsError):
+    """Resource not found (HTTP 404)."""
+
+    pass
+
+
+class ApiError(MailsError):
+    """API returned an error response."""
+
+    def __init__(self, message: str, status_code: int) -> None:
+        super().__init__(message)
+        self.status_code = status_code

mails_agent/models.py

@@ -0,0 +1,43 @@
+"""Data models for the mails-agent SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Email:
+    """Represents an email message."""
+
+    id: str
+    mailbox: str
+    from_address: str
+    from_name: str
+    subject: str
+    direction: str  # 'inbound' | 'outbound'
+    status: str
+    received_at: str
+    has_attachments: bool = False
+    attachment_count: int = 0
+    body_text: str = ""
+    body_html: str = ""
+    code: Optional[str] = None
+
+
+@dataclass
+class SendResult:
+    """Result of a send operation."""
+
+    id: str
+    provider: str
+    provider_id: Optional[str] = None
+
+
+@dataclass
+class VerificationCode:
+    """A verification code extracted from an email."""
+
+    code: str
+    from_address: str
+    subject: str

mails_agent-1.4.0b1.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: mails-agent
+Version: 1.4.0b1
+Summary: Python SDK for mails-agent — email capabilities for AI agents
+Project-URL: Homepage, https://mails0.com
+Project-URL: Repository, https://github.com/Digidai/mails-python
+Project-URL: Documentation, https://github.com/Digidai/mails-python#readme
+Author: Gene Dai
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,email,mails,verification-code
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# mails-agent
+
+Python SDK for [mails0.com](https://mails0.com) -- email capabilities for AI agents.
+
+## Install
+
+```bash
+pip install mails-agent
+```
+
+## Quick start
+
+```python
+from mails_agent import MailsClient
+
+client = MailsClient(
+    api_url="https://mails-worker.your-domain.com",
+    token="your-api-token",
+    mailbox="agent@mails0.com",
+)
+
+# Send an email
+result = client.send(
+    to="user@example.com",
+    subject="Hello from my agent",
+    text="This email was sent by an AI agent.",
+)
+print(f"Sent: {result.id}")
+
+# Check inbox
+emails = client.get_inbox(limit=5)
+for email in emails:
+    print(f"{email.from_address}: {email.subject}")
+
+# Wait for a verification code (long-polls up to 30s)
+code = client.wait_for_code(timeout=30)
+if code:
+    print(f"Got code: {code.code}")
+```
+
+## API reference
+
+### `MailsClient(api_url, token, mailbox, *, timeout=60.0)`
+
+Create a synchronous client. Supports use as a context manager:
+
+```python
+with MailsClient(api_url, token, mailbox) as client:
+    emails = client.get_inbox()
+```
+
+---
+
+### `send(to, subject, *, text=None, html=None, reply_to=None, attachments=None) -> SendResult`
+
+Send an email. `to` can be a single address or a list.
+
+```python
+result = client.send(
+    to=["alice@example.com", "bob@example.com"],
+    subject="Team update",
+    html="<h1>Update</h1><p>Everything is on track.</p>",
+    reply_to="noreply@mails0.com",
+)
+```
+
+**Attachments** are passed as a list of dicts:
+
+```python
+client.send(
+    to="user@example.com",
+    subject="Report",
+    text="See attached.",
+    attachments=[{
+        "filename": "report.pdf",
+        "content": base64_encoded_string,
+        "content_type": "application/pdf",
+    }],
+)
+```
+
+---
+
+### `get_inbox(*, limit=20, offset=0, direction=None, query=None) -> list[Email]`
+
+Fetch emails from the inbox with optional filtering.
+
+```python
+# Get latest 10 inbound emails
+emails = client.get_inbox(limit=10, direction="inbound")
+
+# Search for emails containing "invoice"
+emails = client.get_inbox(query="invoice")
+```
+
+---
+
+### `search(query, *, limit=20, direction=None) -> list[Email]`
+
+Search emails by query string. Convenience wrapper around `get_inbox`.
+
+```python
+results = client.search("verification code", limit=5)
+```
+
+---
+
+### `get_email(email_id) -> Email`
+
+Fetch a single email by its ID. Raises `NotFoundError` if it does not exist.
+
+```python
+email = client.get_email("abc-123")
+print(email.body_text)
+```
+
+---
+
+### `wait_for_code(*, timeout=30) -> VerificationCode | None`
+
+Long-poll the server for a verification code. Returns `None` if no code arrives within the timeout.
+
+```python
+code = client.wait_for_code(timeout=60)
+if code:
+    print(f"Code: {code.code}, From: {code.from_address}")
+```
+
+---
+
+### `delete_email(email_id) -> bool`
+
+Delete an email. Returns `True` if deleted, `False` if not found.
+
+```python
+deleted = client.delete_email("abc-123")
+```
+
+## Async usage
+
+All methods are available as `async` via `AsyncMailsClient`:
+
+```python
+import asyncio
+from mails_agent import AsyncMailsClient
+
+async def main():
+    async with AsyncMailsClient(
+        api_url="https://mails-worker.your-domain.com",
+        token="your-api-token",
+        mailbox="agent@mails0.com",
+    ) as client:
+        # Send
+        result = await client.send("user@example.com", "Hello", text="Hi!")
+
+        # Inbox
+        emails = await client.get_inbox()
+
+        # Wait for code
+        code = await client.wait_for_code(timeout=30)
+
+asyncio.run(main())
+```
+
+## Data models
+
+### `Email`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `str` | Unique email ID |
+| `mailbox` | `str` | Mailbox address |
+| `from_address` | `str` | Sender email |
+| `from_name` | `str` | Sender display name |
+| `subject` | `str` | Subject line |
+| `direction` | `str` | `"inbound"` or `"outbound"` |
+| `status` | `str` | `"received"`, `"sent"`, `"failed"`, `"queued"` |
+| `received_at` | `str` | ISO 8601 timestamp |
+| `has_attachments` | `bool` | Whether email has attachments |
+| `attachment_count` | `int` | Number of attachments |
+| `body_text` | `str` | Plain text body |
+| `body_html` | `str` | HTML body |
+| `code` | `str \| None` | Extracted verification code, if any |
+
+### `SendResult`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `str` | Message ID |
+| `provider` | `str` | Send provider used |
+| `provider_id` | `str \| None` | Provider-specific ID |
+
+### `VerificationCode`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `code` | `str` | The verification code |
+| `from_address` | `str` | Sender of the code email |
+| `subject` | `str` | Subject of the code email |
+
+## Exceptions
+
+| Exception | When |
+|-----------|------|
+| `MailsError` | Base class for all SDK errors |
+| `AuthError` | 401 or 403 response |
+| `NotFoundError` | 404 response |
+| `ApiError` | Any other non-2xx response (has `.status_code`) |
+
+## License
+
+MIT

mails_agent-1.4.0b1.dist-info/RECORD

@@ -0,0 +1,8 @@
+mails_agent/__init__.py,sha256=8Qm9eTDhl9s4s76uhGyaFTLVFjLS9xRzaPAdFUJIuBA,458
+mails_agent/client.py,sha256=pJiovsmHz-0bmFd9nkkFr79uC1SH7YRMWcL8TBwE6dU,12984
+mails_agent/exceptions.py,sha256=oJau3nBfIXi5r1s1Tv1vJa5Ec_udzg52w971AaVaDf4,521
+mails_agent/models.py,sha256=sNbZyOO22snc53EfBABawsocBObxi6xLOqSntcChm1Y,811
+mails_agent-1.4.0b1.dist-info/METADATA,sha256=0rJfUIBxlAJaqdgGAksn0q4BIZsvVxXp_0xj66tUQ98,5623
+mails_agent-1.4.0b1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+mails_agent-1.4.0b1.dist-info/licenses/LICENSE,sha256=TPvRtAS8APyBl4qODyF_s2fUg5i1NPrR5I540nqbQhk,1065
+mails_agent-1.4.0b1.dist-info/RECORD,,

mails_agent-1.4.0b1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mails_agent-1.4.0b1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gene Dai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.