{"id":3441,"library":"customerio","title":"Customer.io Python Client","description":"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.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/customerio/customerio-python","tags":["marketing automation","email","push notifications","sms","analytics","crm","customer engagement"],"install":[{"cmd":"pip install customerio","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"HTTP client for API communication.","package":"requests","optional":false}],"imports":[{"symbol":"Client","correct":"from customerio import Client"}],"quickstart":{"code":"import os\nfrom customerio import Client\n\n# It's recommended to load credentials from environment variables\nsite_id = os.environ.get('CUSTOMERIO_SITE_ID', 'YOUR_SITE_ID')\napi_key = os.environ.get('CUSTOMERIO_API_KEY', 'YOUR_API_KEY')\napp_key = os.environ.get('CUSTOMERIO_APP_KEY', 'YOUR_APP_KEY') # For Transactional API\n\n# Initialize the client. A single client can handle both Track and App APIs.\ncio = Client(site_id=site_id, api_key=api_key, app_key=app_key)\n\n# 1. Identify a user (Track API)\ntry:\n    response = cio.identify(\n        customer_id=\"customer_123\",\n        email=\"user@example.com\",\n        first_name=\"John\",\n        last_name=\"Doe\",\n        created_at=1678886400 # Unix timestamp (e.g., for March 15, 2023)\n    )\n    print(f\"Identify response: {response.status_code} {response.text}\")\nexcept Exception as e:\n    print(f\"Error identifying user: {e}\")\n\n# 2. Track an event for a user (Track API)\ntry:\n    response = cio.track(\n        customer_id=\"customer_123\",\n        name=\"product_purchased\",\n        data={\n            \"product_id\": \"SKU456\",\n            \"price\": 99.99,\n            \"currency\": \"USD\"\n        }\n    )\n    print(f\"Track event response: {response.status_code} {response.text}\")\nexcept Exception as e:\n    print(f\"Error tracking event: {e}\")\n\n# 3. Send a transactional email (App API, requires app_key)\n# Ensure 'transactional_message_id' corresponds to an existing template in Customer.io\nif app_key != 'YOUR_APP_KEY': # Check if app_key was actually provided from env\n    try:\n        response = cio.send_email(\n            to=\"user@example.com\",\n            transactional_message_id=123, # Replace with your actual transactional email ID\n            message_data={\n                \"name\": \"John Doe\",\n                \"item\": \"Widget\"\n            }\n        )\n        print(f\"Send email response: {response.status_code} {response.text}\")\n    except Exception as e:\n        print(f\"Error sending email: {e}\")\nelse:\n    print(\"Skipping transactional email example: CUSTOMERIO_APP_KEY not configured.\")\n\nprint(\"Customer.io operations complete (check console for API responses).\")","lang":"python","description":"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."},"warnings":[{"fix":"Pass `site_id` and `api_key` for tracking/identifying users, and `app_key` for transactional messages (e.g., `cio.send_email`).","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}