Registry / communication / customerio

customerio

JSON →
library3.2.0pypypi✓ verified 22d ago

The official Python client library for Customer.io, providing bindings to their Track API (for user identification and event tracking) and App API (for transactional emails, push notifications, SMS, and inbox messages). Currently at version 2.3.0, it sees regular minor updates to support new Customer.io API features.

pip install customerio
INSTALL
IMPORT
SIG · CUSTOMERIO
C
customerio
communicationpythonv3.2.0
Install
2.2s avg
Import
372ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.380s · 21.2MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.2s · import 0.364s · 22MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

APIClient
from customerio import APIClient
from customerio import Client
CustomerIO
from customerio import CustomerIO
CustomerIOException
from customerio import CustomerIOException

Initialize the `Client` with your Customer.io credentials (Site ID, API Key, and optionally App Key for transactional messages) and perform common operations like identifying users, tracking events, and sending transactional emails.

import os from customerio import Client # It's recommended to load credentials from environment variables site_id = os.environ.get('CUSTOMERIO_SITE_ID', 'YOUR_SITE_ID') api_key = os.environ.get('CUSTOMERIO_API_KEY', 'YOUR_API_KEY') app_key = os.environ.get('CUSTOMERIO_APP_KEY', 'YOUR_APP_KEY') # For Transactional API # Initialize the client. A single client can handle both Track and App APIs. cio = Client(site_id=site_id, api_key=api_key, app_key=app_key) # 1. Identify a user (Track API) try: response = cio.identify( customer_id="customer_123", email="user@example.com", first_name="John", last_name="Doe", created_at=1678886400 # Unix timestamp (e.g., for March 15, 2023) ) print(f"Identify response: {response.status_code} {response.text}") except Exception as e: print(f"Error identifying user: {e}") # 2. Track an event for a user (Track API) try: response = cio.track( customer_id="customer_123", name="product_purchased", data={ "product_id": "SKU456", "price": 99.99, "currency": "USD" } ) print(f"Track event response: {response.status_code} {response.text}") except Exception as e: print(f"Error tracking event: {e}") # 3. Send a transactional email (App API, requires app_key) # Ensure 'transactional_message_id' corresponds to an existing template in Customer.io if app_key != 'YOUR_APP_KEY': # Check if app_key was actually provided from env try: response = cio.send_email( to="user@example.com", transactional_message_id=123, # Replace with your actual transactional email ID message_data={ "name": "John Doe", "item": "Widget" } ) print(f"Send email response: {response.status_code} {response.text}") except Exception as e: print(f"Error sending email: {e}") else: print("Skipping transactional email example: CUSTOMERIO_APP_KEY not configured.") print("Customer.io operations complete (check console for API responses).")
Debug
Known issues
gotchaCustomer.io uses separate API keys for different functionalities: `site_id` and `api_key` are for the Track API (identify, track, page), while `app_key` is for the App API (transactional emails, SMS, push, inbox). Ensure you provide the correct keys for the operations you intend to perform. All three can be passed to the `Client` constructor.
fix
Pass `site_id` and `api_key` for tracking/identifying users, and `app_key` for transactional messages (e.g., `cio.send_email`).
affects: >=2.0.0
gotchaThe `customerio-python` client makes synchronous HTTP requests. In high-volume or performance-critical applications, this can block the event loop. Consider using a separate thread, process, or an asynchronous task queue (e.g., Celery) to offload Customer.io API calls if non-blocking behavior is required.
fix
Implement API calls in a background task, separate thread, or use an async worker queue (e.g., Celery, RQ) to process Customer.io operations without blocking the main application thread.
affects: >=1.0.0
gotchaThe library version (e.g., `2.x`) is independent of the Customer.io API versions (e.g., Track API v2, App API v2). While the `customerio-python` 2.x client is designed to work with the latest Customer.io APIs, ensure your understanding aligns with the specific API documentation for feature compatibility.
fix
Always refer to the official Customer.io API documentation alongside the Python client library documentation for the most up-to-date API specifics and feature availability.
affects: >=2.0.0
gotchaAPI calls can fail due to network issues, invalid data, or authentication problems. The client returns `requests.Response` objects, but it's crucial to check `response.raise_for_status()` or inspect `response.status_code` and `response.text` to handle errors gracefully and avoid silent failures.
fix
Wrap API calls in `try...except` blocks and check the response status (e.g., `response.raise_for_status()` or `if not response.ok:`) to log or handle errors appropriately.
affects: >=1.0.0
Upgrade
Version history
3.2.0latest on PyPI · released Jul 24, 2026
Audit
Dependencies
requestsrequiredHTTP client for API communication.
Agent activity
41 hits · last 30 days
node
36
OpenAI (training)
1
Resources
customerio — pip install customerio · libregistry