Metadata-Version: 2.1
Name: keplars
Version: 2.1.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/KeplarsHQ/python-examples
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}')
```

