bavimail 0.1.0__tar.gz

bavimail-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.tox/
+.venv/
+venv/
+.idea

bavimail-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

bavimail-0.1.0/LICENSE

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

bavimail-0.1.0/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: bavimail
+Version: 0.1.0
+Summary: Python SDK for the Bavimail email service API
+Project-URL: Homepage, https://github.com/Bavlio/bavimail-python
+Project-URL: Documentation, https://github.com/Bavlio/bavimail-python#readme
+Author: Bavlio, samcannas
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0.0,>=0.24.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bavimail-python
+
+Python SDK for the [Bavimail](https://github.com/Bavlio/bavimail-python) email service API.
+
+## Installation
+
+```bash
+pip install bavimail
+```
+
+## Quick Start
+
+### Synchronous
+
+```python
+from bavimail import Bavimail
+
+client = Bavimail(
+    api_key="bvm_your_api_key",
+    base_url="https://mail.yourdomain.com",
+)
+
+# List domains
+domains = client.domains.list()
+for d in domains:
+    print(f"{d.domain} ({d.status})")
+
+# Send an email
+email = client.emails.send(
+    alias_id="your-alias-id",
+    to_email="recipient@example.com",
+    subject="Hello!",
+    body="<p>Welcome!</p>",
+)
+print(f"Sent: {email.id} (status: {email.status})")
+
+client.close()
+```
+
+### Asynchronous
+
+Every method has an `_async` variant. Use `async with` for automatic cleanup:
+
+```python
+import asyncio
+from bavimail import Bavimail
+
+async def main():
+    async with Bavimail(
+        api_key="bvm_your_api_key",
+        base_url="https://mail.yourdomain.com",
+    ) as client:
+        domains = await client.domains.list_async()
+        email = await client.emails.send_async(
+            alias_id="your-alias-id",
+            to_email="recipient@example.com",
+            subject="Hello!",
+            body="<p>Welcome!</p>",
+        )
+
+asyncio.run(main())
+```
+
+## Resources
+
+### Domains
+
+```python
+# Create a domain
+domain = client.domains.create("example.com", "AWS")
+
+# Get setup instructions (DNS records)
+setup = client.domains.get_setup(domain.id)
+for record in setup.dns_records:
+    print(f"{record.type} {record.name} -> {record.value}")
+
+# Check DNS verification status
+dns = client.domains.get_dns_status(domain.id)
+print(f"Verified: {dns.overall_progress.verified}/{dns.overall_progress.total_records}")
+
+# Trigger verification
+domain = client.domains.verify(domain.id)
+
+# Update domain settings
+domain = client.domains.update(domain.id, is_active=False)
+
+# Delete
+client.domains.delete(domain.id)
+```
+
+### Aliases
+
+```python
+alias = client.aliases.create(domain.id, "support")
+aliases = client.aliases.list(domain_id=domain.id)
+client.aliases.update(alias.id, "info")
+client.aliases.delete(alias.id)
+```
+
+### Emails (Outbound)
+
+```python
+email = client.emails.send(
+    alias_id=alias.id,
+    to_email="user@example.com",
+    subject="Welcome",
+    body="<h1>Hello!</h1>",
+    track_opens=True,
+    attachments=[{
+        "filename": "doc.pdf",
+        "content": "<base64-encoded-content>",
+        "mime_type": "application/pdf",
+    }],
+)
+
+emails = client.emails.list(alias_id=alias.id, limit=50)
+email = client.emails.get(email.id)
+```
+
+### Inbound Emails
+
+```python
+# List with filters
+emails = client.inbound_emails.list(alias_id=alias.id, limit=25)
+
+# Get full detail
+detail = client.inbound_emails.get(email_id)
+
+# Download raw RFC822 email
+raw = client.inbound_emails.download_raw(email_id)
+
+# Download attachment by index
+attachment = client.inbound_emails.download_attachment(email_id, 0)
+
+# Tag management
+client.inbound_emails.add_tags(email_id, ["tag-id-1", "tag-id-2"])
+tags = client.inbound_emails.get_tags(email_id)
+client.inbound_emails.replace_tags(email_id, ["tag-id-3"])
+client.inbound_emails.remove_tag(email_id, "tag-id-3")
+
+# Delete
+client.inbound_emails.delete(email_id)
+```
+
+### Conversations
+
+```python
+conversations = client.conversations.list(limit=20)
+detail = client.conversations.get(conversation_id)
+for msg in detail.messages:
+    print(f"[{msg.direction}] {msg.from_email}: {msg.subject}")
+```
+
+### Tags
+
+```python
+tag = client.tags.create("important", color="#ff0000", is_pinned=True)
+tags = client.tags.list()
+tag = client.tags.update(tag.id, name="critical")
+client.tags.delete(tag.id)
+```
+
+### Webhooks
+
+```python
+# Create (returns secret, shown once!)
+wh = client.webhooks.create(
+    url="https://hooks.example.com/bavimail",
+    event_types=["email.inbound.received", "domain.verified"],
+)
+print(f"Secret: {wh.secret}")  # Store this!
+
+# Verify
+wh = client.webhooks.verify(wh.id, "verification-code-from-endpoint")
+
+# Manage
+webhooks = client.webhooks.list()
+client.webhooks.update(wh.id, is_active=True)
+client.webhooks.test(wh.id)
+secret = client.webhooks.rotate_secret(wh.id)
+client.webhooks.delete(wh.id)
+```
+
+## Pagination
+
+Use `iter_pages` / `iter_pages_async` to iterate through all results:
+
+```python
+from bavimail import iter_pages, iter_pages_async
+
+# Sync
+for email in iter_pages(client.inbound_emails.list, alias_id="...", page_size=25):
+    print(email.subject)
+
+# Async
+async for email in iter_pages_async(client.inbound_emails.list_async, page_size=25):
+    print(email.subject)
+```
+
+## Webhook Signature Verification
+
+Verify incoming webhook signatures in your handler:
+
+```python
+from bavimail import verify_webhook_signature, WebhookVerificationError
+
+try:
+    verify_webhook_signature(
+        payload=request.body,
+        signature=request.headers["x-webhook-signature"],
+        timestamp=request.headers["x-webhook-timestamp"],
+        secret="your-hex-secret",
+    )
+except WebhookVerificationError as e:
+    print(f"Invalid webhook: {e}")
+```
+
+## Error Handling
+
+All API errors raise typed exceptions:
+
+```python
+from bavimail import (
+    NotFoundError,
+    ValidationError,
+    ConflictError,
+    AuthenticationError,
+    RateLimitError,
+    APIError,
+)
+
+try:
+    client.domains.get("nonexistent")
+except NotFoundError as e:
+    print(f"Not found: {e.message}")
+    print(f"Error code: {e.code}")       # e.g. "DOMAIN_NOT_FOUND"
+    print(f"Category: {e.category}")      # e.g. "not_found"
+    print(f"Request ID: {e.request_id}")  # For debugging
+    print(f"Context: {e.context}")        # e.g. {"field": "domain_id", "value": "nonexistent"}
+except APIError as e:
+    print(f"API error ({e.status_code}): {e.message}")
+```
+
+## Custom HTTP Client
+
+Pass a custom `httpx.Client` for advanced configuration (proxies, custom TLS, retries):
+
+```python
+import httpx
+
+custom = httpx.Client(
+    transport=httpx.HTTPTransport(retries=3),
+    timeout=60.0,
+)
+
+client = Bavimail(
+    api_key="bvm_...",
+    base_url="https://mail.yourdomain.com",
+    http_client=custom,
+)
+```
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Type check
+mypy src/bavimail --strict
+
+# Lint
+ruff check src/ tests/
+```
+
+## License
+
+MIT

bavimail-0.1.0/README.md

@@ -0,0 +1,281 @@
+# bavimail-python
+
+Python SDK for the [Bavimail](https://github.com/Bavlio/bavimail-python) email service API.
+
+## Installation
+
+```bash
+pip install bavimail
+```
+
+## Quick Start
+
+### Synchronous
+
+```python
+from bavimail import Bavimail
+
+client = Bavimail(
+    api_key="bvm_your_api_key",
+    base_url="https://mail.yourdomain.com",
+)
+
+# List domains
+domains = client.domains.list()
+for d in domains:
+    print(f"{d.domain} ({d.status})")
+
+# Send an email
+email = client.emails.send(
+    alias_id="your-alias-id",
+    to_email="recipient@example.com",
+    subject="Hello!",
+    body="<p>Welcome!</p>",
+)
+print(f"Sent: {email.id} (status: {email.status})")
+
+client.close()
+```
+
+### Asynchronous
+
+Every method has an `_async` variant. Use `async with` for automatic cleanup:
+
+```python
+import asyncio
+from bavimail import Bavimail
+
+async def main():
+    async with Bavimail(
+        api_key="bvm_your_api_key",
+        base_url="https://mail.yourdomain.com",
+    ) as client:
+        domains = await client.domains.list_async()
+        email = await client.emails.send_async(
+            alias_id="your-alias-id",
+            to_email="recipient@example.com",
+            subject="Hello!",
+            body="<p>Welcome!</p>",
+        )
+
+asyncio.run(main())
+```
+
+## Resources
+
+### Domains
+
+```python
+# Create a domain
+domain = client.domains.create("example.com", "AWS")
+
+# Get setup instructions (DNS records)
+setup = client.domains.get_setup(domain.id)
+for record in setup.dns_records:
+    print(f"{record.type} {record.name} -> {record.value}")
+
+# Check DNS verification status
+dns = client.domains.get_dns_status(domain.id)
+print(f"Verified: {dns.overall_progress.verified}/{dns.overall_progress.total_records}")
+
+# Trigger verification
+domain = client.domains.verify(domain.id)
+
+# Update domain settings
+domain = client.domains.update(domain.id, is_active=False)
+
+# Delete
+client.domains.delete(domain.id)
+```
+
+### Aliases
+
+```python
+alias = client.aliases.create(domain.id, "support")
+aliases = client.aliases.list(domain_id=domain.id)
+client.aliases.update(alias.id, "info")
+client.aliases.delete(alias.id)
+```
+
+### Emails (Outbound)
+
+```python
+email = client.emails.send(
+    alias_id=alias.id,
+    to_email="user@example.com",
+    subject="Welcome",
+    body="<h1>Hello!</h1>",
+    track_opens=True,
+    attachments=[{
+        "filename": "doc.pdf",
+        "content": "<base64-encoded-content>",
+        "mime_type": "application/pdf",
+    }],
+)
+
+emails = client.emails.list(alias_id=alias.id, limit=50)
+email = client.emails.get(email.id)
+```
+
+### Inbound Emails
+
+```python
+# List with filters
+emails = client.inbound_emails.list(alias_id=alias.id, limit=25)
+
+# Get full detail
+detail = client.inbound_emails.get(email_id)
+
+# Download raw RFC822 email
+raw = client.inbound_emails.download_raw(email_id)
+
+# Download attachment by index
+attachment = client.inbound_emails.download_attachment(email_id, 0)
+
+# Tag management
+client.inbound_emails.add_tags(email_id, ["tag-id-1", "tag-id-2"])
+tags = client.inbound_emails.get_tags(email_id)
+client.inbound_emails.replace_tags(email_id, ["tag-id-3"])
+client.inbound_emails.remove_tag(email_id, "tag-id-3")
+
+# Delete
+client.inbound_emails.delete(email_id)
+```
+
+### Conversations
+
+```python
+conversations = client.conversations.list(limit=20)
+detail = client.conversations.get(conversation_id)
+for msg in detail.messages:
+    print(f"[{msg.direction}] {msg.from_email}: {msg.subject}")
+```
+
+### Tags
+
+```python
+tag = client.tags.create("important", color="#ff0000", is_pinned=True)
+tags = client.tags.list()
+tag = client.tags.update(tag.id, name="critical")
+client.tags.delete(tag.id)
+```
+
+### Webhooks
+
+```python
+# Create (returns secret, shown once!)
+wh = client.webhooks.create(
+    url="https://hooks.example.com/bavimail",
+    event_types=["email.inbound.received", "domain.verified"],
+)
+print(f"Secret: {wh.secret}")  # Store this!
+
+# Verify
+wh = client.webhooks.verify(wh.id, "verification-code-from-endpoint")
+
+# Manage
+webhooks = client.webhooks.list()
+client.webhooks.update(wh.id, is_active=True)
+client.webhooks.test(wh.id)
+secret = client.webhooks.rotate_secret(wh.id)
+client.webhooks.delete(wh.id)
+```
+
+## Pagination
+
+Use `iter_pages` / `iter_pages_async` to iterate through all results:
+
+```python
+from bavimail import iter_pages, iter_pages_async
+
+# Sync
+for email in iter_pages(client.inbound_emails.list, alias_id="...", page_size=25):
+    print(email.subject)
+
+# Async
+async for email in iter_pages_async(client.inbound_emails.list_async, page_size=25):
+    print(email.subject)
+```
+
+## Webhook Signature Verification
+
+Verify incoming webhook signatures in your handler:
+
+```python
+from bavimail import verify_webhook_signature, WebhookVerificationError
+
+try:
+    verify_webhook_signature(
+        payload=request.body,
+        signature=request.headers["x-webhook-signature"],
+        timestamp=request.headers["x-webhook-timestamp"],
+        secret="your-hex-secret",
+    )
+except WebhookVerificationError as e:
+    print(f"Invalid webhook: {e}")
+```
+
+## Error Handling
+
+All API errors raise typed exceptions:
+
+```python
+from bavimail import (
+    NotFoundError,
+    ValidationError,
+    ConflictError,
+    AuthenticationError,
+    RateLimitError,
+    APIError,
+)
+
+try:
+    client.domains.get("nonexistent")
+except NotFoundError as e:
+    print(f"Not found: {e.message}")
+    print(f"Error code: {e.code}")       # e.g. "DOMAIN_NOT_FOUND"
+    print(f"Category: {e.category}")      # e.g. "not_found"
+    print(f"Request ID: {e.request_id}")  # For debugging
+    print(f"Context: {e.context}")        # e.g. {"field": "domain_id", "value": "nonexistent"}
+except APIError as e:
+    print(f"API error ({e.status_code}): {e.message}")
+```
+
+## Custom HTTP Client
+
+Pass a custom `httpx.Client` for advanced configuration (proxies, custom TLS, retries):
+
+```python
+import httpx
+
+custom = httpx.Client(
+    transport=httpx.HTTPTransport(retries=3),
+    timeout=60.0,
+)
+
+client = Bavimail(
+    api_key="bvm_...",
+    base_url="https://mail.yourdomain.com",
+    http_client=custom,
+)
+```
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Type check
+mypy src/bavimail --strict
+
+# Lint
+ruff check src/ tests/
+```
+
+## License
+
+MIT

bavimail-0.1.0/examples/async_usage.py

@@ -0,0 +1,40 @@
+"""Async usage of the Bavimail SDK."""
+
+import asyncio
+
+from bavimail import Bavimail, iter_pages_async
+
+
+async def main() -> None:
+    async with Bavimail(
+        api_key="bvm_your_api_key_here",
+        base_url="https://mail.yourdomain.com",
+    ) as client:
+        # List domains
+        domains = await client.domains.list_async()
+        for d in domains:
+            print(f"{d.domain} ({d.status})")
+
+        # Send an email
+        email = await client.emails.send_async(
+            alias_id="your-alias-id",
+            to_email="recipient@example.com",
+            subject="Hello from async!",
+            body="<p>Sent asynchronously.</p>",
+        )
+        print(f"Sent: {email.id}")
+
+        # Paginate through inbound emails
+        async for inbound in iter_pages_async(
+            client.inbound_emails.list_async, page_size=25
+        ):
+            print(f"  {inbound.from_email}: {inbound.subject}")
+
+        # Conversations
+        conversations = await client.conversations.list_async(limit=10)
+        for conv in conversations:
+            print(f"Thread: {conv.subject} ({conv.message_count} messages)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())