Customer.io Python Client

Warnings

• gotcha Customer.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`).
• gotcha The `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.
• gotcha The 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.
• gotcha API 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.

Install

• pip install customerio Install latest version

Imports

• Client

  from customerio import Client

Quickstart

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).")