mailgent-sdk 0.6.2__tar.gz

mailgent_sdk-0.6.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loomal
+
+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.

mailgent_sdk-0.6.2/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: mailgent-sdk
+Version: 0.6.2
+Summary: Official Python SDK for the Mailgent API — identity, mail, vault, calendar, and buyer x402 payments for AI agents
+Author: Mailgent
+License: MIT
+Project-URL: Homepage, https://mailgent.dev
+Project-URL: Documentation, https://docs.mailgent.dev
+Project-URL: Repository, https://github.com/mailgent-dev/mailgent-python
+Project-URL: Issues, https://github.com/mailgent-dev/mailgent-python/issues
+Keywords: mailgent,ai,agent,email,mcp,did,vault,sdk,x402,usdc,payments
+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 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# Mailgent Python SDK
+
+The official Python SDK for the [Mailgent API](https://mailgent.dev) -- identity, mail, vault, calendar, and **Mailgent Pay** for AI agents.
+
+[![PyPI version](https://img.shields.io/pypi/v/mailgent-sdk.svg)](https://pypi.org/project/mailgent-sdk/)
+[![Python 3.9+](https://img.shields.io/pypi/pyversions/mailgent-sdk.svg)](https://pypi.org/project/mailgent-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install mailgent-sdk
+```
+
+> The distribution is `mailgent-sdk` on PyPI, but the import name is `mailgent`.
+
+## Buyer payments (x402)
+
+Pay any x402-protected URL from your project's wallet. Mailgent drives the
+full handshake — discover the 402 challenge, enforce mandate caps, sign
+EIP-3009, retry, and record — then returns a discriminated result.
+
+```python
+result = client.payments.pay(url="https://api.example.com")
+if result["ok"]:
+    print(result["txHash"], result["cost"]["amountUsdc"])
+else:
+    print(result["code"], result["hint"])
+```
+
+Spend policy lives at `client.payments.mandates`. Requires the
+`payments:spend` scope on the API key. See the
+[full payments guide](https://docs.mailgent.dev/payments).
+
+### Webhook signature verification
+
+Mailgent sends `X-Mailgent-Signature: sha256=<hex>` (HMAC-SHA256 of the raw
+request body) along with `X-Mailgent-Event` / `X-Mailgent-Idempotency-Key`.
+The signing secret is generated by Mailgent when you register an endpoint
+in the Console and shown to you exactly once.
+
+```python
+import os
+from fastapi import FastAPI, HTTPException, Request
+from mailgent.webhook import verify_webhook
+
+app = FastAPI()
+
+@app.post("/webhooks/mailgent")
+async def webhook(request: Request):
+    raw = await request.body()
+    ok = verify_webhook(
+        raw,
+        request.headers.get("x-mailgent-signature"),
+        os.environ["MAILGENT_WEBHOOK_SECRET"],
+    )
+    if not ok:
+        raise HTTPException(400, "invalid signature")
+    # de-dupe on x-mailgent-idempotency-key, then handle the event.
+    # Today the only event type is `payment.received`.
+```
+
+## Quick start
+
+```python
+from mailgent import Mailgent
+
+client = Mailgent(api_key="loid-...")
+
+me = client.identity.whoami()
+print(me.email)
+
+client.mail.send(
+    to=["colleague@example.com"],
+    subject="Hello from my agent",
+    text="Sent via the Mailgent Python SDK.",
+)
+```
+
+## Async usage
+
+```python
+from mailgent import AsyncMailgent
+
+async with AsyncMailgent(api_key="loid-...") as client:
+    me = await client.identity.whoami()
+    await client.mail.send(
+        to=["colleague@example.com"],
+        subject="Hello",
+        text="Sent asynchronously.",
+    )
+```
+
+## Authentication
+
+Pass your API key directly, or set the `MAILGENT_API_KEY` environment variable:
+
+```python
+# Explicit
+client = Mailgent(api_key="loid-...")
+
+# From environment
+import os
+os.environ["MAILGENT_API_KEY"] = "loid-..."
+client = Mailgent()
+```
+
+Both `Mailgent` and `AsyncMailgent` support context managers for automatic resource cleanup:
+
+```python
+with Mailgent() as client:
+    me = client.identity.whoami()
+```
+
+## Usage
+
+### Identity
+
+```python
+me = client.identity.whoami()
+print(me.email, me.display_name)
+```
+
+### Vault
+
+The vault is password-manager-style encrypted secret storage (AES-256-GCM at rest). Use `client.vault.store()` for arbitrary types, or the typed helpers below.
+
+```python
+# Simple API key
+client.vault.store_api_key("stripe", "sk_live_...")
+
+# OAuth-style client credentials (client id + secret)
+client.vault.store_api_key("twitter", {
+    "clientId": "abc123",
+    "secret": "def456",
+})
+
+# Credit card (encrypted at rest — this is a secret vault, not a payment processor)
+client.vault.store_card("personal-visa", {
+    "cardholder": "Jane Doe",
+    "number": "4242 4242 4242 4242",
+    "expMonth": "12",
+    "expYear": "2029",
+    "cvc": "123",
+    "zip": "94103",
+}, metadata={"brand": "Visa"})
+
+# Shipping address
+client.vault.store_shipping_address("home", {
+    "name": "Autonomous Agent",
+    "line1": "1 Demo Way",
+    "city": "San Francisco",
+    "state": "CA",
+    "postcode": "94103",
+    "country": "US",
+})
+```
+
+Supported credential types: `LOGIN`, `API_KEY`, `OAUTH`, `TOTP`, `SSH_KEY`, `DATABASE`, `SMTP`, `AWS`, `CERTIFICATE`, `CARD`, `SHIPPING_ADDRESS`, `CUSTOM`.
+
+### More resources
+
+The SDK also exposes `client.mail`, `client.calendar`, `client.logs`, and `client.did`. See the full reference at **[docs.mailgent.dev](https://docs.mailgent.dev)** for request/response shapes, pagination, and end-to-end examples.
+
+## Error handling
+
+All API errors raise `MailgentApiError` with structured fields:
+
+```python
+from mailgent import MailgentApiError
+
+try:
+    client.mail.send(to=["a@b.com"], subject="Hi", text="Hello")
+except MailgentApiError as e:
+    print(e.status)   # HTTP status code
+    print(e.code)     # Error code string
+    print(e.message)  # Human-readable message
+```
+
+## Types
+
+The SDK returns typed dataclasses, not raw dictionaries. API responses are automatically converted from camelCase to snake_case.
+
+| Type | Description |
+|------|-------------|
+| `IdentityResponse` | Agent identity details |
+| `MessageResponse` | Email message |
+| `ThreadResponse` | Thread summary |
+| `ThreadDetailResponse` | Thread with messages |
+| `CredentialMetadata` | Vault credential metadata |
+| `CredentialWithData` | Credential with decrypted data |
+| `ActivityLog` | Single activity log entry |
+| `LogsStats` | Aggregated log statistics |
+| `TotpResponse` | Generated TOTP code |
+| `DidDocument` | DID document |
+
+> **Note:** The `from` field in message responses is exposed as `from_addrs` since `from` is a reserved keyword in Python.
+
+## Requirements
+
+- Python 3.9+
+- [`httpx`](https://www.python-httpx.org/) (installed automatically)
+
+## Links
+
+- [Documentation](https://docs.mailgent.dev)
+- [Console](https://console.mailgent.dev)
+- [Website](https://mailgent.dev)
+- [PyPI](https://pypi.org/project/mailgent-sdk/)
+
+## License
+
+MIT

mailgent_sdk-0.6.2/README.md

@@ -0,0 +1,213 @@
+# Mailgent Python SDK
+
+The official Python SDK for the [Mailgent API](https://mailgent.dev) -- identity, mail, vault, calendar, and **Mailgent Pay** for AI agents.
+
+[![PyPI version](https://img.shields.io/pypi/v/mailgent-sdk.svg)](https://pypi.org/project/mailgent-sdk/)
+[![Python 3.9+](https://img.shields.io/pypi/pyversions/mailgent-sdk.svg)](https://pypi.org/project/mailgent-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install mailgent-sdk
+```
+
+> The distribution is `mailgent-sdk` on PyPI, but the import name is `mailgent`.
+
+## Buyer payments (x402)
+
+Pay any x402-protected URL from your project's wallet. Mailgent drives the
+full handshake — discover the 402 challenge, enforce mandate caps, sign
+EIP-3009, retry, and record — then returns a discriminated result.
+
+```python
+result = client.payments.pay(url="https://api.example.com")
+if result["ok"]:
+    print(result["txHash"], result["cost"]["amountUsdc"])
+else:
+    print(result["code"], result["hint"])
+```
+
+Spend policy lives at `client.payments.mandates`. Requires the
+`payments:spend` scope on the API key. See the
+[full payments guide](https://docs.mailgent.dev/payments).
+
+### Webhook signature verification
+
+Mailgent sends `X-Mailgent-Signature: sha256=<hex>` (HMAC-SHA256 of the raw
+request body) along with `X-Mailgent-Event` / `X-Mailgent-Idempotency-Key`.
+The signing secret is generated by Mailgent when you register an endpoint
+in the Console and shown to you exactly once.
+
+```python
+import os
+from fastapi import FastAPI, HTTPException, Request
+from mailgent.webhook import verify_webhook
+
+app = FastAPI()
+
+@app.post("/webhooks/mailgent")
+async def webhook(request: Request):
+    raw = await request.body()
+    ok = verify_webhook(
+        raw,
+        request.headers.get("x-mailgent-signature"),
+        os.environ["MAILGENT_WEBHOOK_SECRET"],
+    )
+    if not ok:
+        raise HTTPException(400, "invalid signature")
+    # de-dupe on x-mailgent-idempotency-key, then handle the event.
+    # Today the only event type is `payment.received`.
+```
+
+## Quick start
+
+```python
+from mailgent import Mailgent
+
+client = Mailgent(api_key="loid-...")
+
+me = client.identity.whoami()
+print(me.email)
+
+client.mail.send(
+    to=["colleague@example.com"],
+    subject="Hello from my agent",
+    text="Sent via the Mailgent Python SDK.",
+)
+```
+
+## Async usage
+
+```python
+from mailgent import AsyncMailgent
+
+async with AsyncMailgent(api_key="loid-...") as client:
+    me = await client.identity.whoami()
+    await client.mail.send(
+        to=["colleague@example.com"],
+        subject="Hello",
+        text="Sent asynchronously.",
+    )
+```
+
+## Authentication
+
+Pass your API key directly, or set the `MAILGENT_API_KEY` environment variable:
+
+```python
+# Explicit
+client = Mailgent(api_key="loid-...")
+
+# From environment
+import os
+os.environ["MAILGENT_API_KEY"] = "loid-..."
+client = Mailgent()
+```
+
+Both `Mailgent` and `AsyncMailgent` support context managers for automatic resource cleanup:
+
+```python
+with Mailgent() as client:
+    me = client.identity.whoami()
+```
+
+## Usage
+
+### Identity
+
+```python
+me = client.identity.whoami()
+print(me.email, me.display_name)
+```
+
+### Vault
+
+The vault is password-manager-style encrypted secret storage (AES-256-GCM at rest). Use `client.vault.store()` for arbitrary types, or the typed helpers below.
+
+```python
+# Simple API key
+client.vault.store_api_key("stripe", "sk_live_...")
+
+# OAuth-style client credentials (client id + secret)
+client.vault.store_api_key("twitter", {
+    "clientId": "abc123",
+    "secret": "def456",
+})
+
+# Credit card (encrypted at rest — this is a secret vault, not a payment processor)
+client.vault.store_card("personal-visa", {
+    "cardholder": "Jane Doe",
+    "number": "4242 4242 4242 4242",
+    "expMonth": "12",
+    "expYear": "2029",
+    "cvc": "123",
+    "zip": "94103",
+}, metadata={"brand": "Visa"})
+
+# Shipping address
+client.vault.store_shipping_address("home", {
+    "name": "Autonomous Agent",
+    "line1": "1 Demo Way",
+    "city": "San Francisco",
+    "state": "CA",
+    "postcode": "94103",
+    "country": "US",
+})
+```
+
+Supported credential types: `LOGIN`, `API_KEY`, `OAUTH`, `TOTP`, `SSH_KEY`, `DATABASE`, `SMTP`, `AWS`, `CERTIFICATE`, `CARD`, `SHIPPING_ADDRESS`, `CUSTOM`.
+
+### More resources
+
+The SDK also exposes `client.mail`, `client.calendar`, `client.logs`, and `client.did`. See the full reference at **[docs.mailgent.dev](https://docs.mailgent.dev)** for request/response shapes, pagination, and end-to-end examples.
+
+## Error handling
+
+All API errors raise `MailgentApiError` with structured fields:
+
+```python
+from mailgent import MailgentApiError
+
+try:
+    client.mail.send(to=["a@b.com"], subject="Hi", text="Hello")
+except MailgentApiError as e:
+    print(e.status)   # HTTP status code
+    print(e.code)     # Error code string
+    print(e.message)  # Human-readable message
+```
+
+## Types
+
+The SDK returns typed dataclasses, not raw dictionaries. API responses are automatically converted from camelCase to snake_case.
+
+| Type | Description |
+|------|-------------|
+| `IdentityResponse` | Agent identity details |
+| `MessageResponse` | Email message |
+| `ThreadResponse` | Thread summary |
+| `ThreadDetailResponse` | Thread with messages |
+| `CredentialMetadata` | Vault credential metadata |
+| `CredentialWithData` | Credential with decrypted data |
+| `ActivityLog` | Single activity log entry |
+| `LogsStats` | Aggregated log statistics |
+| `TotpResponse` | Generated TOTP code |
+| `DidDocument` | DID document |
+
+> **Note:** The `from` field in message responses is exposed as `from_addrs` since `from` is a reserved keyword in Python.
+
+## Requirements
+
+- Python 3.9+
+- [`httpx`](https://www.python-httpx.org/) (installed automatically)
+
+## Links
+
+- [Documentation](https://docs.mailgent.dev)
+- [Console](https://console.mailgent.dev)
+- [Website](https://mailgent.dev)
+- [PyPI](https://pypi.org/project/mailgent-sdk/)
+
+## License
+
+MIT

mailgent_sdk-0.6.2/mailgent/__init__.py

@@ -0,0 +1,41 @@
+from mailgent.client import Mailgent, AsyncMailgent
+from mailgent.platform_client import MailgentPlatform, AsyncMailgentPlatform
+from mailgent.types import (
+    MessageResponse, ThreadResponse, ThreadDetailResponse,
+    VaultCredentialType,
+    ApiKeySecretData, ApiKeyClientPairData,
+    CardData, CardMetadata, ShippingAddressData,
+    CredentialMetadata, CredentialWithData, IdentityResponse,
+    IdentitySummary, IdentityDetail, CreateIdentityResponse, RotateKeyResponse,
+    CalendarEvent,
+    ActivityLog, LogsStats, TotpResponse, TotpBackupResponse, DidDocument,
+    PaymentEndpointSummary, PaymentSummary, PaymentReceiptBody,
+    PaymentReceipt, PaymentDetail,
+    PAYMENT_ERROR_CODES, PaymentErrorCode,
+    PaymentsPayParams, PaymentsPaySuccess, PaymentsPayFailure, PaymentsPayResponse,
+    PaymentActivityIn, PaymentActivityOut, PaymentActivityRow, PaymentActivityList,
+    Mandate, MandateCreateParams, MandateList,
+)
+from mailgent._errors import MailgentApiError
+
+__version__ = "0.6.2"
+
+__all__ = [
+    "Mailgent", "AsyncMailgent",
+    "MailgentPlatform", "AsyncMailgentPlatform",
+    "MailgentApiError",
+    "MessageResponse", "ThreadResponse", "ThreadDetailResponse",
+    "VaultCredentialType",
+    "ApiKeySecretData", "ApiKeyClientPairData",
+    "CardData", "CardMetadata", "ShippingAddressData",
+    "CredentialMetadata", "CredentialWithData", "IdentityResponse",
+    "IdentitySummary", "IdentityDetail", "CreateIdentityResponse", "RotateKeyResponse",
+    "CalendarEvent",
+    "ActivityLog", "LogsStats", "TotpResponse", "DidDocument",
+    "PaymentEndpointSummary", "PaymentSummary", "PaymentReceiptBody",
+    "PaymentReceipt", "PaymentDetail",
+    "PAYMENT_ERROR_CODES", "PaymentErrorCode",
+    "PaymentsPayParams", "PaymentsPaySuccess", "PaymentsPayFailure", "PaymentsPayResponse",
+    "PaymentActivityIn", "PaymentActivityOut", "PaymentActivityRow", "PaymentActivityList",
+    "Mandate", "MandateCreateParams", "MandateList",
+]

mailgent_sdk-0.6.2/mailgent/_errors.py

@@ -0,0 +1,10 @@
+class MailgentApiError(Exception):
+    """Raised when the Mailgent API returns a non-2xx response."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+    def __repr__(self) -> str:
+        return f"MailgentApiError(status={self.status}, code={self.code!r}, message={self.args[0]!r})"

mailgent_sdk-0.6.2/mailgent/_http.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from mailgent._errors import MailgentApiError
+
+DEFAULT_BASE_URL = "https://api.mailgent.dev"
+DEFAULT_TIMEOUT = 30.0
+
+
+def _build_headers(api_key: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+
+
+def _handle_response(response: httpx.Response) -> Any:
+    if response.status_code == 204:
+        return None
+
+    data = response.json() if response.content else {}
+
+    if not response.is_success:
+        raise MailgentApiError(
+            status=response.status_code,
+            code=data.get("error", "unknown_error"),
+            message=data.get("message", f"Request failed with status {response.status_code}"),
+        )
+
+    return data
+
+
+class SyncHttpClient:
+    def __init__(self, base_url: str, api_key: str, timeout: float = DEFAULT_TIMEOUT) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+
+    def get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        return _handle_response(self._client.get(path, params=params))
+
+    def post(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        return _handle_response(self._client.post(path, json=json))
+
+    def post_unchecked(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        """POST that does not raise on 4xx/5xx — returns the parsed JSON body
+        verbatim. Use for endpoints that encode success/failure in the body
+        (e.g. ``/v0/payments/pay`` returns ``{"ok": ...}`` with status 200,
+        402, or 503)."""
+        response = self._client.post(path, json=json)
+        if response.status_code == 204:
+            return None
+        return response.json() if response.content else {}
+
+    def put(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        return _handle_response(self._client.put(path, json=json))
+
+    def patch(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        return _handle_response(self._client.patch(path, json=json))
+
+    def delete(self, path: str) -> Any:
+        return _handle_response(self._client.delete(path))
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncHttpClient:
+    def __init__(self, base_url: str, api_key: str, timeout: float = DEFAULT_TIMEOUT) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+
+    async def get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        return _handle_response(await self._client.get(path, params=params))
+
+    async def post(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        return _handle_response(await self._client.post(path, json=json))
+
+    async def post_unchecked(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        """Async sibling of :meth:`SyncHttpClient.post_unchecked`."""
+        response = await self._client.post(path, json=json)
+        if response.status_code == 204:
+            return None
+        return response.json() if response.content else {}
+
+    async def put(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        return _handle_response(await self._client.put(path, json=json))
+
+    async def patch(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        return _handle_response(await self._client.patch(path, json=json))
+
+    async def delete(self, path: str) -> Any:
+        return _handle_response(await self._client.delete(path))
+
+    async def close(self) -> None:
+        await self._client.aclose()