keplars 1.0.0__tar.gz

keplars-1.0.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.1
+Name: keplars
+Version: 1.0.0
+Summary: Official Python SDK for Keplars Email API - modern transactional email service with priority-based delivery
+Home-page: https://keplars.com
+License: MIT
+Keywords: keplars,email,transactional,api,sdk,priority,scheduling
+Author: Keplars
+Author-email: support@keplars.com
+Requires-Python: >=3.8,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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
+Requires-Dist: httpx (>=0.26.0,<0.27.0)
+Requires-Dist: pydantic[email] (>=2.5.0,<3.0.0)
+Project-URL: Documentation, https://docs.keplars.com
+Project-URL: Repository, https://github.com/Swing-Technologies/keplers-mail-sdk
+Description-Content-Type: text/markdown
+
+# Keplars Email SDK for Python
+
+Official Python SDK for the Keplars Email API - modern transactional email service with priority-based delivery.
+
+## Installation
+
+```bash
+pip install keplars
+```
+
+or with Poetry:
+
+```bash
+poetry add keplars
+```
+
+## Quick Start
+
+### Synchronous Client
+
+```python
+from keplars import Keplars
+
+client = Keplars(api_key='kms_<workspaceId>.live_<secret>')
+
+result = client.emails.send_instant(
+    **{'from': 'noreply@yourdomain.com'},
+    to='user@example.com',
+    subject='Your verification code is 123456',
+    html='<p>Your verification code is <strong>123456</strong></p>'
+)
+
+print(result.data.job_id)
+```
+
+### Async Client
+
+```python
+import asyncio
+from keplars import AsyncKeplars
+
+async def main():
+    async with AsyncKeplars(api_key='kms_<workspaceId>.live_<secret>') as client:
+        result = await client.emails.send_instant(
+            **{'from': 'noreply@yourdomain.com'},
+            to='user@example.com',
+            subject='Welcome!',
+            html='<h1>Welcome aboard</h1>'
+        )
+        print(result.data.job_id)
+
+asyncio.run(main())
+```
+
+### API Key Types
+
+| Type | Format | Used for |
+|---|---|---|
+| Regular | `kms_<id>.live_<secret>` | Email sending |
+| Admin | `kms_<id>.adm_<secret>` | Contacts, audiences, automations, domains |
+
+## Email Sending
+
+### Priority Levels
+
+| Method | Delivery | Use case |
+|---|---|---|
+| `send_instant` | 0–5 sec | OTPs, login codes, critical alerts |
+| `send_high` | 0–30 sec | Transactional, notifications |
+| `send_async` / `send` | 0–5 min | General transactional |
+| `send_bulk` | Idle | Newsletters, marketing |
+
+### Response Shape
+
+```python
+result.success      # True
+result.message      # 'Email queued'
+result.data.job_id  # 'job_abc123'
+result.data.priority # 'instant'
+```
+
+### Send with Recipients
+
+```python
+result = client.emails.send_high(
+    **{'from': 'noreply@yourdomain.com'},
+    to=[{'email': 'user@example.com', 'name': 'John Doe'}],
+    cc=[{'email': 'manager@example.com'}],
+    subject='Order Confirmation',
+    html='<p>Your order has been confirmed</p>'
+)
+```
+
+### Send with Template
+
+```python
+result = client.emails.send(
+    **{'from': 'noreply@yourdomain.com'},
+    to='user@example.com',
+    subject='Password Reset',
+    template_id='tpl_reset_password',
+    template_data={'name': 'John', 'reset_link': 'https://example.com/reset/abc'}
+)
+```
+
+### Schedule Email
+
+```python
+result = client.emails.schedule(
+    **{'from': 'newsletter@yourdomain.com'},
+    to='user@example.com',
+    subject='Your weekly digest',
+    html='<p>Here is your weekly digest...</p>',
+    scheduled_for='2026-06-01T09:00:00Z',
+    priority='bulk'
+)
+```
+
+## Contacts (Admin API Key Required)
+
+```python
+admin_client = Keplars(api_key='kms_<workspaceId>.adm_<secret>')
+
+admin_client.contacts.add(email='user@example.com', name='John Doe', audience_id='aud_abc123')
+
+contact = admin_client.contacts.get('user@example.com')
+
+contacts = admin_client.contacts.list(audience_id='aud_abc123', page=1, limit=20)
+
+admin_client.contacts.update('user@example.com', name='Jane Doe')
+
+admin_client.contacts.delete('user@example.com')
+```
+
+## Audiences (Admin API Key Required)
+
+```python
+audience = admin_client.audiences.create('Newsletter Subscribers', description='Main list')
+
+audiences = admin_client.audiences.list(page=1, limit=20)
+
+audience = admin_client.audiences.get('aud_abc123')
+
+admin_client.audiences.delete('aud_abc123')
+```
+
+## Automations (Admin API Key Required)
+
+```python
+automations = admin_client.automations.list()
+
+automation = admin_client.automations.get('auto_abc123')
+
+admin_client.automations.enroll('auto_abc123', 'user@example.com')
+
+admin_client.automations.unenroll('auto_abc123', 'user@example.com')
+```
+
+## Domains (Admin API Key Required)
+
+```python
+domain = admin_client.domains.add('mail.yourcompany.com')
+
+domains = admin_client.domains.list()
+
+status = admin_client.domains.get_status('dom_abc123')
+
+result = admin_client.domains.verify('dom_abc123')
+
+api_key = admin_client.domains.create_api_key(domain_id='dom_abc123', name='Production Key')
+
+admin_client.domains.delete('dom_abc123')
+```
+
+## Error Handling
+
+```python
+from keplars import (
+    Keplars,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+)
+
+try:
+    result = client.emails.send_instant(...)
+except AuthenticationError:
+    print('Invalid API key')
+except RateLimitError as e:
+    print(f'Rate limited, retry after: {e.retry_after}s')
+except ValidationError as e:
+    print(f'Validation error: {e}')
+```
+

keplars-1.0.0/README.md

@@ -0,0 +1,193 @@
+# Keplars Email SDK for Python
+
+Official Python SDK for the Keplars Email API - modern transactional email service with priority-based delivery.
+
+## Installation
+
+```bash
+pip install keplars
+```
+
+or with Poetry:
+
+```bash
+poetry add keplars
+```
+
+## Quick Start
+
+### Synchronous Client
+
+```python
+from keplars import Keplars
+
+client = Keplars(api_key='kms_<workspaceId>.live_<secret>')
+
+result = client.emails.send_instant(
+    **{'from': 'noreply@yourdomain.com'},
+    to='user@example.com',
+    subject='Your verification code is 123456',
+    html='<p>Your verification code is <strong>123456</strong></p>'
+)
+
+print(result.data.job_id)
+```
+
+### Async Client
+
+```python
+import asyncio
+from keplars import AsyncKeplars
+
+async def main():
+    async with AsyncKeplars(api_key='kms_<workspaceId>.live_<secret>') as client:
+        result = await client.emails.send_instant(
+            **{'from': 'noreply@yourdomain.com'},
+            to='user@example.com',
+            subject='Welcome!',
+            html='<h1>Welcome aboard</h1>'
+        )
+        print(result.data.job_id)
+
+asyncio.run(main())
+```
+
+### API Key Types
+
+| Type | Format | Used for |
+|---|---|---|
+| Regular | `kms_<id>.live_<secret>` | Email sending |
+| Admin | `kms_<id>.adm_<secret>` | Contacts, audiences, automations, domains |
+
+## Email Sending
+
+### Priority Levels
+
+| Method | Delivery | Use case |
+|---|---|---|
+| `send_instant` | 0–5 sec | OTPs, login codes, critical alerts |
+| `send_high` | 0–30 sec | Transactional, notifications |
+| `send_async` / `send` | 0–5 min | General transactional |
+| `send_bulk` | Idle | Newsletters, marketing |
+
+### Response Shape
+
+```python
+result.success      # True
+result.message      # 'Email queued'
+result.data.job_id  # 'job_abc123'
+result.data.priority # 'instant'
+```
+
+### Send with Recipients
+
+```python
+result = client.emails.send_high(
+    **{'from': 'noreply@yourdomain.com'},
+    to=[{'email': 'user@example.com', 'name': 'John Doe'}],
+    cc=[{'email': 'manager@example.com'}],
+    subject='Order Confirmation',
+    html='<p>Your order has been confirmed</p>'
+)
+```
+
+### Send with Template
+
+```python
+result = client.emails.send(
+    **{'from': 'noreply@yourdomain.com'},
+    to='user@example.com',
+    subject='Password Reset',
+    template_id='tpl_reset_password',
+    template_data={'name': 'John', 'reset_link': 'https://example.com/reset/abc'}
+)
+```
+
+### Schedule Email
+
+```python
+result = client.emails.schedule(
+    **{'from': 'newsletter@yourdomain.com'},
+    to='user@example.com',
+    subject='Your weekly digest',
+    html='<p>Here is your weekly digest...</p>',
+    scheduled_for='2026-06-01T09:00:00Z',
+    priority='bulk'
+)
+```
+
+## Contacts (Admin API Key Required)
+
+```python
+admin_client = Keplars(api_key='kms_<workspaceId>.adm_<secret>')
+
+admin_client.contacts.add(email='user@example.com', name='John Doe', audience_id='aud_abc123')
+
+contact = admin_client.contacts.get('user@example.com')
+
+contacts = admin_client.contacts.list(audience_id='aud_abc123', page=1, limit=20)
+
+admin_client.contacts.update('user@example.com', name='Jane Doe')
+
+admin_client.contacts.delete('user@example.com')
+```
+
+## Audiences (Admin API Key Required)
+
+```python
+audience = admin_client.audiences.create('Newsletter Subscribers', description='Main list')
+
+audiences = admin_client.audiences.list(page=1, limit=20)
+
+audience = admin_client.audiences.get('aud_abc123')
+
+admin_client.audiences.delete('aud_abc123')
+```
+
+## Automations (Admin API Key Required)
+
+```python
+automations = admin_client.automations.list()
+
+automation = admin_client.automations.get('auto_abc123')
+
+admin_client.automations.enroll('auto_abc123', 'user@example.com')
+
+admin_client.automations.unenroll('auto_abc123', 'user@example.com')
+```
+
+## Domains (Admin API Key Required)
+
+```python
+domain = admin_client.domains.add('mail.yourcompany.com')
+
+domains = admin_client.domains.list()
+
+status = admin_client.domains.get_status('dom_abc123')
+
+result = admin_client.domains.verify('dom_abc123')
+
+api_key = admin_client.domains.create_api_key(domain_id='dom_abc123', name='Production Key')
+
+admin_client.domains.delete('dom_abc123')
+```
+
+## Error Handling
+
+```python
+from keplars import (
+    Keplars,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+)
+
+try:
+    result = client.emails.send_instant(...)
+except AuthenticationError:
+    print('Invalid API key')
+except RateLimitError as e:
+    print(f'Rate limited, retry after: {e.retry_after}s')
+except ValidationError as e:
+    print(f'Validation error: {e}')
+```

keplars-1.0.0/pyproject.toml

@@ -0,0 +1,72 @@
+[tool.poetry]
+name = "keplars"
+version = "1.0.0"
+description = "Official Python SDK for Keplars Email API - modern transactional email service with priority-based delivery"
+authors = ["Keplars <support@keplars.com>"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://keplars.com"
+repository = "https://github.com/Swing-Technologies/keplers-mail-sdk"
+documentation = "https://docs.keplars.com"
+keywords = ["keplars", "email", "transactional", "api", "sdk", "priority", "scheduling"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Email",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+packages = [{include = "keplars", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.8"
+httpx = "^0.26.0"
+pydantic = {version = "^2.5.0", extras = ["email"]}
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.3"
+pytest-asyncio = "^0.23.2"
+pytest-cov = "^4.1.0"
+pytest-mock = "^3.12.0"
+black = "^23.12.1"
+isort = "^5.13.2"
+mypy = "^1.8.0"
+ruff = "^0.1.9"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 100
+target-version = ['py38']
+include = '\.pyi?$'
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.mypy]
+python_version = "3.8"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"
+addopts = "-v --cov=keplars --cov-report=term-missing"
+asyncio_mode = "auto"

keplars-1.0.0/src/keplars/__init__.py

@@ -0,0 +1,74 @@
+from .client import Keplars, AsyncKeplars
+from .errors import (
+    KeplarsError,
+    ValidationError,
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    DomainNotVerifiedError,
+    InternalError,
+    NetworkError,
+    NotFoundError,
+    PlanLimitError,
+    QuotaExceededError,
+    RateLimitError,
+)
+from .models import (
+    EmailPriority,
+    ErrorCode,
+    KeplarsConfig,
+    EmailRecipient,
+    SendEmailRequest,
+    SendEmailResponse,
+    SendEmailData,
+    ScheduleEmailRequest,
+    ScheduledEmailResponse,
+    Contact,
+    Audience,
+    Automation,
+    DomainListItem,
+    PaginatedMeta,
+    ErrorDetail,
+    RateLimitInfo,
+)
+from .utils import (
+    verify_webhook_signature,
+    render_template,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Keplars",
+    "AsyncKeplars",
+    "KeplarsError",
+    "ValidationError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ConflictError",
+    "DomainNotVerifiedError",
+    "InternalError",
+    "NetworkError",
+    "NotFoundError",
+    "PlanLimitError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "EmailPriority",
+    "ErrorCode",
+    "KeplarsConfig",
+    "EmailRecipient",
+    "SendEmailRequest",
+    "SendEmailResponse",
+    "SendEmailData",
+    "ScheduleEmailRequest",
+    "ScheduledEmailResponse",
+    "Contact",
+    "Audience",
+    "Automation",
+    "DomainListItem",
+    "PaginatedMeta",
+    "ErrorDetail",
+    "RateLimitInfo",
+    "verify_webhook_signature",
+    "render_template",
+]

keplars-1.0.0/src/keplars/audiences.py

@@ -0,0 +1,90 @@
+from typing import Any, Dict, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .client import Keplars, AsyncKeplars
+
+
+class AudiencesResource:
+    def __init__(self, client: "Keplars") -> None:
+        self._client = client
+
+    def create(self, name: str, description: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        response_data, _ = self._client._request(
+            "POST", "/api/v1/public/audiences/add-audience", body
+        )
+        return response_data
+
+    def list(self, page: Optional[int] = None, limit: Optional[int] = None) -> Dict[str, Any]:
+        params: Dict[str, Any] = {}
+        if page is not None:
+            params["page"] = page
+        if limit is not None:
+            params["limit"] = limit
+
+        query = ""
+        if params:
+            query = "?" + "&".join(f"{k}={v}" for k, v in params.items())
+
+        response_data, _ = self._client._request(
+            "GET", f"/api/v1/public/audiences/get-audiences{query}"
+        )
+        return response_data
+
+    def get(self, id: str) -> Dict[str, Any]:
+        response_data, _ = self._client._request(
+            "GET", f"/api/v1/public/audiences/get-audience?id={id}"
+        )
+        return response_data
+
+    def delete(self, id: str) -> Dict[str, Any]:
+        response_data, _ = self._client._request(
+            "DELETE", f"/api/v1/public/audiences/delete-audience?id={id}"
+        )
+        return response_data
+
+
+class AsyncAudiencesResource:
+    def __init__(self, client: "AsyncKeplars") -> None:
+        self._client = client
+
+    async def create(self, name: str, description: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        response_data, _ = await self._client._request(
+            "POST", "/api/v1/public/audiences/add-audience", body
+        )
+        return response_data
+
+    async def list(
+        self, page: Optional[int] = None, limit: Optional[int] = None
+    ) -> Dict[str, Any]:
+        params: Dict[str, Any] = {}
+        if page is not None:
+            params["page"] = page
+        if limit is not None:
+            params["limit"] = limit
+
+        query = ""
+        if params:
+            query = "?" + "&".join(f"{k}={v}" for k, v in params.items())
+
+        response_data, _ = await self._client._request(
+            "GET", f"/api/v1/public/audiences/get-audiences{query}"
+        )
+        return response_data
+
+    async def get(self, id: str) -> Dict[str, Any]:
+        response_data, _ = await self._client._request(
+            "GET", f"/api/v1/public/audiences/get-audience?id={id}"
+        )
+        return response_data
+
+    async def delete(self, id: str) -> Dict[str, Any]:
+        response_data, _ = await self._client._request(
+            "DELETE", f"/api/v1/public/audiences/delete-audience?id={id}"
+        )
+        return response_data