Metadata-Version: 2.4
Name: bulko
Version: 0.1.0
Summary: Python SDK and CLI for the Bulko campaign automation API
Author-email: Bulko <support@bulko.io>
License-Expression: MIT
Project-URL: Homepage, https://bulko.io/?utm_source=pypi&utm_medium=sdk&utm_campaign=bulko_api
Project-URL: Documentation, https://github.com/blureshot/bulko-python#readme
Project-URL: Repository, https://github.com/blureshot/bulko-python
Project-URL: Issues, https://github.com/blureshot/bulko-python/issues
Keywords: bulko,email,campaigns,automation,sdk,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Bulko Python

Dependency-free Python SDK and CLI for the [Bulko API](https://bulko.io/api/v1/openapi.yaml).

## Install

```bash
pip install bulko
```

Until the first PyPI release, install directly from GitHub:

```bash
pip install git+https://github.com/blureshot/bulko-python.git
```

## SDK

```python
import os
from bulko import Bulko

client = Bulko(os.environ["BULKO_API_KEY"])

print(client.account.balance())

campaign = client.campaigns.launch(
    name="Product update",
    subject="A useful update for your team",
    body="<p>Hello, here is the update you requested.</p>",
    recipients=["alex@example.com", {"email": "sam@example.com", "name": "Sam"}],
    reply_to="replies@example.com",
)

print(client.campaigns.stats(campaign["id"]))
```

Available resources are `campaigns`, `subscribers`, `replies`, `account`, and `smtp_accesses`. `AsyncBulko` provides async helpers for read operations. API keys must remain server-side.

## CLI

```bash
export BULKO_API_KEY=bulko_live_...

bulko balance
bulko campaign-stats 42
bulko replies --status positive --limit 25
bulko smtp-accesses
bulko import-subscribers contacts.txt --list-name "Webinar attendees"
```

Campaign launch is intentionally protected by an explicit flag:

```bash
bulko launch-campaign \
  --name "Product update" \
  --subject "A useful update" \
  --html-file message.html \
  --recipients-file recipients.txt \
  --confirm-send
```

Only send permission-based email that complies with the [Bulko Acceptable Use Policy](https://bulko.io/en/acceptable-use-policy/?utm_source=github&utm_medium=sdk&utm_campaign=bulko_api) and applicable law.

## Errors

HTTP failures map to typed exceptions: `ValidationError`, `AuthenticationError`, `InsufficientCreditsError`, `ContentBlockedError`, `NotFoundError`, and `RateLimitError`. Each API exception exposes `status_code`, `response`, and `request_id`.

## Development

```bash
python -m pip install -e . ruff build
ruff check .
python -m unittest discover -s tests -v
python -m build
```

## License

MIT
