keplars 1.4.0

Official Python SDK for Keplars Email API - modern transactional email service with priority-based delivery

Keplars Email SDK for Python

Official Python SDK for the Keplars Email API - modern transactional email service with priority-based delivery.

Installation

pip install keplars

or with Poetry:

poetry add keplars

Quick Start

Synchronous Client

from keplars import Keplars

client = Keplars(api_key='kms_<workspaceId>.live_<secret>')

result = client.emails.send_instant(
    **{'from': '[e-mail]'},
    to='[e-mail]',
    subject='Your verification code is 123456',
    html='<p>Your verification code is <strong>123456</strong></p>'
)

print(result.data.job_id)

Async Client

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': '[e-mail]'},
            to='[e-mail]',
            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

result.success      # True
result.message      # 'Email queued'
result.data.job_id  # 'job_abc123'
result.data.priority # 'instant'

Send with Recipients

result = client.emails.send_high(
    **{'from': '[e-mail]'},
    to=[{'email': '[e-mail]', 'name': 'John Doe'}],
    cc=[{'email': '[e-mail]'}],
    subject='Order Confirmation',
    html='<p>Your order has been confirmed</p>'
)

Send with Template

result = client.emails.send(
    **{'from': '[e-mail]'},
    to='[e-mail]',
    subject='Password Reset',
    template_id='tpl_reset_password',
    template_data={'name': 'John', 'reset_link': 'https://example.com/reset/abc'}
)

Schedule Email

result = client.emails.schedule(
    **{'from': '[e-mail]'},
    to='[e-mail]',
    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)

admin_client = Keplars(api_key='kms_<workspaceId>.adm_<secret>')

admin_client.contacts.add(email='[e-mail]', name='John Doe', audience_id='aud_abc123')

contact = admin_client.contacts.get('[e-mail]')

contacts = admin_client.contacts.list(audience_id='aud_abc123', page=1, limit=20)

admin_client.contacts.update('[e-mail]', name='Jane Doe')

admin_client.contacts.delete('[e-mail]')

Audiences (Admin API Key Required)

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)

automations = admin_client.automations.list()

automation = admin_client.automations.get('auto_abc123')

admin_client.automations.enroll('auto_abc123', '[e-mail]')

admin_client.automations.unenroll('auto_abc123', '[e-mail]')

Domains (Admin API Key Required)

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

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}')