Bulko Python

Dependency-free Python SDK and CLI for the Bulko API.

Install

pip install bulko

SDK

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

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:

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 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

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

License

MIT