Customer.io transactional email and messaging client for Altissimo Python projects.
- 📋 Template emails via
send_email()— uses Customer.io transactional templates - 📧 Plain text emails via
send_text()— inline content, no template required - 🎨 HTML emails via
send_html()— inline content, no template required - 🌍 Region support — US and EU data centers
- 🏗️ Factory method —
CustomerIOClient.from_env()readsCUSTOMERIO_API_KEYfrom the environment - 🔌 Optional dependency —
customerioSDK is lazily imported with a helpful error message - 📐 Typed — full type annotations with
py.typedPEP 561 marker - ✅ Consistent return type — all methods return a
SendResultdataclass - 🔄 Retry with backoff — configurable retry for transient failures
- Python 3.11+
pip install altissimo-customerio[customerio] # core + Customer.io SDKfrom altissimo.customerio import CustomerIOClient
client = CustomerIOClient.from_env()
# Template email (most common)
result = client.send_email(
to="user@example.com",
transactional_message_id="3",
message_data={"first_name": "Alice", "year": 2026},
)
# Plain text
result = client.send_text(
to="user@example.com",
subject="Hello",
body="Welcome aboard!",
)
# HTML
result = client.send_html(
to="user@example.com",
subject="Hello",
html="<h1>Welcome!</h1>",
reply_to="support@example.com",
)
assert result.ok
print(result.delivery_id)| Variable | Description | Default |
|---|---|---|
CUSTOMERIO_API_KEY |
Customer.io App API key | (required) |
CUSTOMERIO_REGION |
Data center region (us or eu) |
us |
client = CustomerIOClient(
app_api_key="your-api-key",
region="us", # "us" or "eu"
default_from="noreply@lived.com", # default sender
max_retries=3, # retry transient failures
retry_delay=1.0, # base delay (seconds)
)| Method | Description |
|---|---|
CustomerIOClient(app_api_key, region?, default_from?) |
Create a client with an explicit API key |
CustomerIOClient.from_env(env_var?, region?, default_from?) |
Create a client from an environment variable |
send_email(to, transactional_message_id, message_data?, ...) |
Send a template-based transactional email |
send_text(to, subject, body, from_email?, reply_to?, ...) |
Send a plain-text email (inline content) |
send_html(to, subject, html, from_email?, reply_to?, ...) |
Send an HTML email (inline content) |
| Field | Type | Description |
|---|---|---|
ok |
bool |
Whether the request succeeded |
delivery_id |
str |
Delivery ID from Customer.io |
status_code |
int |
HTTP status code (0 on exception) |
body |
dict[str, Any] |
Response body |
error |
str | None |
Error message on failure |
altissimo.customerio
├── __init__.py # Public API surface
├── client.py # CustomerIOClient with lazy SDK initialization
├── exceptions.py # CustomerIOError, CustomerIOImportError
├── models.py # EmailAddress, SendResult dataclasses
└── py.typed # PEP 561 marker
# Install all dependencies
poetry sync
# Run tests
poetry run pytest
# Run tests with coverage
poetry run pytest --cov=altissimo --cov-report=term-missing
# Run linters
poetry run ruff check .
poetry run ruff format --check .See CONTRIBUTING.md for detailed development guidelines.
See CHANGELOG.md for version history.
For reporting security vulnerabilities, see SECURITY.md.
Apache License 2.0 — see LICENSE for details.