mailcue 0.1.0__tar.gz

mailcue-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

mailcue-0.1.0/LICENSE

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

mailcue-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: mailcue
+Version: 0.1.0
+Summary: Official Python SDK for MailCue — open-source email testing and production server.
+Project-URL: Homepage, https://github.com/Olib-AI/mailcue
+Project-URL: Repository, https://github.com/Olib-AI/mailcue
+Project-URL: Documentation, https://github.com/Olib-AI/mailcue#readme
+Project-URL: Issues, https://github.com/Olib-AI/mailcue/issues
+Author-email: Olib AI <hello@olib.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,dovecot,email,email-testing,imap,mailbox,mailcue,postfix,smtp,transactional-email
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+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 :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: typing-extensions>=4.7.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MailCue Python SDK
+
+Official Python client for [MailCue](https://github.com/Olib-AI/mailcue) — the
+open-source email testing and production server (Postfix + Dovecot + FastAPI +
+React) packaged as one Docker container.
+
+The SDK is the same in dev and prod: point it at `http://localhost:8088` while
+you build, then swap `base_url` to your production MailCue deployment when you
+ship.
+
+## Install
+
+```bash
+pip install mailcue
+```
+
+Requires Python 3.9+.
+
+## Quick start: send an email
+
+```python
+from mailcue import Mailcue
+
+client = Mailcue(api_key="mc_xxx")  # base_url defaults to http://localhost:8088
+
+result = client.emails.send(
+    from_="hello@example.com",
+    to=["user@example.com"],
+    subject="Welcome",
+    html="<h1>Hi there</h1>",
+)
+print(result.message_id)
+```
+
+Need async? Use `AsyncMailcue` — same surface, all methods become coroutines:
+
+```python
+import asyncio
+from mailcue import AsyncMailcue
+
+async def main() -> None:
+    async with AsyncMailcue(api_key="mc_xxx") as client:
+        await client.emails.send(
+            from_="hello@example.com",
+            to=["user@example.com"],
+            subject="Welcome",
+            html="<h1>Hi there</h1>",
+        )
+
+asyncio.run(main())
+```
+
+## Listing an inbox
+
+```python
+inbox = client.emails.list(mailbox="user@example.com", page_size=20)
+for email in inbox.emails:
+    print(email.uid, email.subject, email.from_address)
+
+detail = client.emails.get(inbox.emails[0].uid, mailbox="user@example.com")
+print(detail.text_body)
+```
+
+## Attachments
+
+`attachments` accepts raw `bytes`, `str`, or a `pathlib.Path`. The SDK
+base64-encodes the content for you.
+
+```python
+from pathlib import Path
+
+client.emails.send(
+    from_="hello@example.com",
+    to=["user@example.com"],
+    subject="Invoice",
+    html="<p>See attached.</p>",
+    attachments=[
+        {
+            "filename": "invoice.pdf",
+            "content_type": "application/pdf",
+            "content": Path("./invoice.pdf"),
+        }
+    ],
+)
+```
+
+## Real-time events (SSE)
+
+```python
+for event in client.events.stream():
+    print(event.event_type, event.data)
+```
+
+The async version:
+
+```python
+async with AsyncMailcue(api_key="mc_xxx") as client:
+    async for event in client.events.stream():
+        print(event.event_type, event.data)
+```
+
+The SSE client auto-reconnects with exponential backoff if the connection
+drops.
+
+## Error handling
+
+```python
+from mailcue import (
+    Mailcue,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+client = Mailcue(api_key="mc_xxx")
+
+try:
+    client.emails.get("not-a-real-uid", mailbox="user@example.com")
+except NotFoundError as exc:
+    print("missing:", exc)
+except RateLimitError as exc:
+    print(f"slow down; retry after {exc.retry_after}s")
+except AuthenticationError:
+    print("bad API key")
+except ValidationError as exc:
+    print("server rejected the request:", exc.detail)
+```
+
+## Configuration
+
+```python
+client = Mailcue(
+    api_key="mc_xxx",                        # or bearer_token="eyJ..."
+    base_url="https://mail.example.com",     # default: http://localhost:8088
+    timeout=30.0,                            # seconds
+    max_retries=3,                           # 502/503/504 + network errors
+    verify=True,                             # set False for self-signed dev TLS
+)
+```
+
+You can also inject your own `httpx.Client` / `httpx.AsyncClient` via
+`http_client=` for advanced cases (custom transports, proxies, mTLS).
+
+## Resources
+
+| Resource | Methods |
+|----------|---------|
+| `client.emails` | `send`, `list`, `get`, `get_raw`, `get_attachment`, `delete`, `inject`, `bulk_inject` |
+| `client.mailboxes` | `list`, `create`, `delete`, `stats`, `purge`, `list_emails` |
+| `client.domains` | `list`, `create`, `get`, `verify_dns`, `delete` |
+| `client.aliases` | `list`, `create`, `get`, `update`, `delete` |
+| `client.gpg` | `list`, `generate`, `get`, `export_public`, `import_key`, `publish`, `delete` |
+| `client.api_keys` | `list`, `create`, `delete` |
+| `client.system` | `health`, `get_certificate`, `download_certificate`, `settings`, `tls_status` |
+| `client.events` | `stream()` (SSE iterator) |
+
+## License
+
+MIT — see `LICENSE`.
+
+Project home: https://github.com/Olib-AI/mailcue

mailcue-0.1.0/README.md

@@ -0,0 +1,162 @@
+# MailCue Python SDK
+
+Official Python client for [MailCue](https://github.com/Olib-AI/mailcue) — the
+open-source email testing and production server (Postfix + Dovecot + FastAPI +
+React) packaged as one Docker container.
+
+The SDK is the same in dev and prod: point it at `http://localhost:8088` while
+you build, then swap `base_url` to your production MailCue deployment when you
+ship.
+
+## Install
+
+```bash
+pip install mailcue
+```
+
+Requires Python 3.9+.
+
+## Quick start: send an email
+
+```python
+from mailcue import Mailcue
+
+client = Mailcue(api_key="mc_xxx")  # base_url defaults to http://localhost:8088
+
+result = client.emails.send(
+    from_="hello@example.com",
+    to=["user@example.com"],
+    subject="Welcome",
+    html="<h1>Hi there</h1>",
+)
+print(result.message_id)
+```
+
+Need async? Use `AsyncMailcue` — same surface, all methods become coroutines:
+
+```python
+import asyncio
+from mailcue import AsyncMailcue
+
+async def main() -> None:
+    async with AsyncMailcue(api_key="mc_xxx") as client:
+        await client.emails.send(
+            from_="hello@example.com",
+            to=["user@example.com"],
+            subject="Welcome",
+            html="<h1>Hi there</h1>",
+        )
+
+asyncio.run(main())
+```
+
+## Listing an inbox
+
+```python
+inbox = client.emails.list(mailbox="user@example.com", page_size=20)
+for email in inbox.emails:
+    print(email.uid, email.subject, email.from_address)
+
+detail = client.emails.get(inbox.emails[0].uid, mailbox="user@example.com")
+print(detail.text_body)
+```
+
+## Attachments
+
+`attachments` accepts raw `bytes`, `str`, or a `pathlib.Path`. The SDK
+base64-encodes the content for you.
+
+```python
+from pathlib import Path
+
+client.emails.send(
+    from_="hello@example.com",
+    to=["user@example.com"],
+    subject="Invoice",
+    html="<p>See attached.</p>",
+    attachments=[
+        {
+            "filename": "invoice.pdf",
+            "content_type": "application/pdf",
+            "content": Path("./invoice.pdf"),
+        }
+    ],
+)
+```
+
+## Real-time events (SSE)
+
+```python
+for event in client.events.stream():
+    print(event.event_type, event.data)
+```
+
+The async version:
+
+```python
+async with AsyncMailcue(api_key="mc_xxx") as client:
+    async for event in client.events.stream():
+        print(event.event_type, event.data)
+```
+
+The SSE client auto-reconnects with exponential backoff if the connection
+drops.
+
+## Error handling
+
+```python
+from mailcue import (
+    Mailcue,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+client = Mailcue(api_key="mc_xxx")
+
+try:
+    client.emails.get("not-a-real-uid", mailbox="user@example.com")
+except NotFoundError as exc:
+    print("missing:", exc)
+except RateLimitError as exc:
+    print(f"slow down; retry after {exc.retry_after}s")
+except AuthenticationError:
+    print("bad API key")
+except ValidationError as exc:
+    print("server rejected the request:", exc.detail)
+```
+
+## Configuration
+
+```python
+client = Mailcue(
+    api_key="mc_xxx",                        # or bearer_token="eyJ..."
+    base_url="https://mail.example.com",     # default: http://localhost:8088
+    timeout=30.0,                            # seconds
+    max_retries=3,                           # 502/503/504 + network errors
+    verify=True,                             # set False for self-signed dev TLS
+)
+```
+
+You can also inject your own `httpx.Client` / `httpx.AsyncClient` via
+`http_client=` for advanced cases (custom transports, proxies, mTLS).
+
+## Resources
+
+| Resource | Methods |
+|----------|---------|
+| `client.emails` | `send`, `list`, `get`, `get_raw`, `get_attachment`, `delete`, `inject`, `bulk_inject` |
+| `client.mailboxes` | `list`, `create`, `delete`, `stats`, `purge`, `list_emails` |
+| `client.domains` | `list`, `create`, `get`, `verify_dns`, `delete` |
+| `client.aliases` | `list`, `create`, `get`, `update`, `delete` |
+| `client.gpg` | `list`, `generate`, `get`, `export_public`, `import_key`, `publish`, `delete` |
+| `client.api_keys` | `list`, `create`, `delete` |
+| `client.system` | `health`, `get_certificate`, `download_certificate`, `settings`, `tls_status` |
+| `client.events` | `stream()` (SSE iterator) |
+
+## License
+
+MIT — see `LICENSE`.
+
+Project home: https://github.com/Olib-AI/mailcue

mailcue-0.1.0/mailcue/__init__.py

@@ -0,0 +1,110 @@
+"""MailCue Python SDK.
+
+Drop-in client for the MailCue REST API. Both ``Mailcue`` (sync) and
+``AsyncMailcue`` (async) clients expose the same resource surface:
+``emails``, ``mailboxes``, ``domains``, ``aliases``, ``gpg``,
+``api_keys``, ``system``, and the SSE ``events`` stream.
+
+Example:
+    >>> from mailcue import Mailcue
+    >>> client = Mailcue(api_key="mc_...")
+    >>> client.emails.send(
+    ...     from_="hello@example.com",
+    ...     to=["user@example.com"],
+    ...     subject="Welcome",
+    ...     html="<h1>Hi</h1>",
+    ... )
+"""
+
+from __future__ import annotations
+
+from mailcue._version import __version__
+from mailcue.client import AsyncMailcue, Mailcue
+from mailcue.exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    MailcueError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    ValidationError,
+)
+from mailcue.transport import DEFAULT_BASE_URL
+from mailcue.types import (
+    Alias,
+    AliasListResponse,
+    ApiKey,
+    AttachmentInfo,
+    BulkInjectResponse,
+    CreatedApiKey,
+    DnsCheckResponse,
+    DnsRecordInfo,
+    Domain,
+    DomainDetail,
+    DomainListResponse,
+    EmailDetail,
+    EmailListResponse,
+    EmailSummary,
+    Event,
+    FolderInfo,
+    GpgEmailInfo,
+    GpgKey,
+    GpgKeyExport,
+    GpgKeyListResponse,
+    HealthResponse,
+    KeyserverPublishResult,
+    Mailbox,
+    MailboxListResponse,
+    MailboxStats,
+    SendResult,
+    SignatureStatus,
+    TlsCertificateStatus,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Alias",
+    "AliasListResponse",
+    "ApiKey",
+    "AsyncMailcue",
+    "AttachmentInfo",
+    "AuthenticationError",
+    "AuthorizationError",
+    "BulkInjectResponse",
+    "ConflictError",
+    "CreatedApiKey",
+    "DnsCheckResponse",
+    "DnsRecordInfo",
+    "Domain",
+    "DomainDetail",
+    "DomainListResponse",
+    "EmailDetail",
+    "EmailListResponse",
+    "EmailSummary",
+    "Event",
+    "FolderInfo",
+    "GpgEmailInfo",
+    "GpgKey",
+    "GpgKeyExport",
+    "GpgKeyListResponse",
+    "HealthResponse",
+    "KeyserverPublishResult",
+    "Mailbox",
+    "MailboxListResponse",
+    "MailboxStats",
+    "Mailcue",
+    "MailcueError",
+    "NetworkError",
+    "NotFoundError",
+    "RateLimitError",
+    "SendResult",
+    "ServerError",
+    "SignatureStatus",
+    "TimeoutError",
+    "TlsCertificateStatus",
+    "ValidationError",
+    "__version__",
+]

mailcue-0.1.0/mailcue/_version.py

@@ -0,0 +1,5 @@
+"""Single source of truth for the package version."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

mailcue-0.1.0/mailcue/auth.py

@@ -0,0 +1,50 @@
+"""Auth header builders.
+
+MailCue accepts either an API key (``X-API-Key: mc_...``) or a JWT bearer
+token (``Authorization: Bearer ...``). The transport calls ``headers()``
+on the configured strategy for each request.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Dict
+
+
+class AuthStrategy(ABC):
+    """Strategy that produces auth headers for outgoing requests."""
+
+    @abstractmethod
+    def headers(self) -> Dict[str, str]:
+        """Return the headers to merge into each request."""
+
+
+class ApiKeyAuth(AuthStrategy):
+    """Authenticate using a MailCue API key."""
+
+    def __init__(self, api_key: str) -> None:
+        if not api_key:
+            raise ValueError("api_key must not be empty")
+        self._api_key = api_key
+
+    def headers(self) -> Dict[str, str]:
+        return {"X-API-Key": self._api_key}
+
+
+class BearerAuth(AuthStrategy):
+    """Authenticate using a JWT bearer token."""
+
+    def __init__(self, token: str) -> None:
+        if not token:
+            raise ValueError("token must not be empty")
+        self._token = token
+
+    def headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self._token}"}
+
+
+class NoAuth(AuthStrategy):
+    """No-op strategy used for unauthenticated endpoints (e.g. /health)."""
+
+    def headers(self) -> Dict[str, str]:
+        return {}