Customer.io Python bindings

This module has been tested with Python 3.6, 3.7, 3.8 and 3.9.

Installing

pip install customerio

Usage

from customerio import CustomerIO, Regions
cio = CustomerIO(site_id, api_key, region=Regions.US)
cio.identify(id="5", email='[email protected]', name='Bob', plan='premium')
cio.track(customer_id="5", name='purchased')
cio.track(customer_id="5", name='purchased', price=23.45)

Instantiating customer.io object

Create an instance of the client with your Customer.io credentials.

from customerio import CustomerIO, Regions
cio = CustomerIO(site_id, api_key, region=Regions.US)

region is optional and takes one of two values—Regions.US or Regions.EU. If you do not specify your region, we assume that your account is based in the US (Regions.US). If your account is based in the EU and you do not provide the correct region (Regions.EU), we'll route requests to our EU data centers accordingly, however this may cause data to be logged in the US.

Create or update a Customer.io customer profile

cio.identify(id="5", email='[email protected]', name='Bob', plan='premium')

Only the id field is used to identify the customer here. Using an existing id with a different email (or any other attribute) will update/overwrite any pre-existing values for that field.

You can pass any keyword arguments to the identify and track methods. These kwargs will be converted to custom attributes.

See original REST documentation here

Track a custom event

cio.track(customer_id="5", name='purchased')

Track a custom event with custom data values

cio.track(customer_id="5", name='purchased', price=23.45, product="widget")

You can pass any keyword arguments to the identify and track methods. These kwargs will be converted to custom attributes.

See original REST documentation here

Backfill a custom event

from datetime import datetime, timedelta

customer_id = "5"
event_type = "purchase"

# Backfill an event one hour in the past
event_date = datetime.utcnow() - timedelta(hours=1)
cio.backfill(customer_id, event_type, event_date, price=23.45, coupon=True)

event_timestamp = 1408482633
cio.backfill(customer_id, event_type, event_timestamp, price=34.56)

event_timestamp = "1408482680"
cio.backfill(customer_id, event_type, event_timestamp, price=45.67)

Event timestamp may be passed as a datetime.datetime object, an integer or a string UNIX timestamp

Keyword arguments to backfill work the same as a call to cio.track.

See original REST documentation here

Delete a customer profile

cio.delete(customer_id="5")

Deletes the customer profile for a specified customer.

This method returns nothing. Attempts to delete non-existent customers will not raise any errors.

See original REST documentation here

You can pass any keyword arguments to the identify and track methods. These kwargs will be converted to custom attributes.

Add a device

cio.add_device(customer_id="1", device_id='device_hash', platform='ios')

Adds the device device_hash with the platform ios for a specified customer.

Supported platforms are ios and android.

Optionally, last_used can be passed in to specify the last touch of the device. Otherwise, this attribute is set by the API.

cio.add_device(customer_id="1", device_id='device_hash', platform='ios', last_used=1514764800})

This method returns nothing.

Delete a device

cio.delete_device(customer_id="1", device_id='device_hash')

Deletes the specified device for a specified customer.

This method returns nothing. Attempts to delete non-existent devices will not raise any errors.

Suppress a customer

cio.suppress(customer_id="1")

Suppresses the specified customer. They will be deleted from Customer.io, and we will ignore all further attempts to identify or track activity for the suppressed customer ID

See REST documentation here

Unsuppress a customer

cio.unsuppress(customer_id="1")

Unsuppresses the specified customer. We will remove the supplied id from our suppression list and start accepting new identify and track calls for the customer as normal

See REST documentation here

Send Transactional Messages

To use the Transactional API, instantiate the Customer.io object using an app key and create a request object containing:

• transactional_message_id: the ID of the transactional message you want to send, or the body, from, and subject of a new message.
• to: the email address of your recipients
• an identifiers object containing the id of your recipient. If the id does not exist, Customer.io will create it.
• a message_data object containing properties that you want reference in your message using Liquid.
• You can also send attachments with your message. Use attach to encode attachments.

Use send_email referencing your request to send a transactional message. Learn more about transactional messages and SendEmailRequest properties.

from customerio import APIClient, Regions, SendEmailRequest
client = APIClient("your API key", region=Regions.US)

request = SendEmailRequest(
  to="[email protected]",
  transactional_message_id="3",
  message_data={
    "name": "person",
    "items": [
      {
        "name": "shoes",
        "price": "59.99",
      },
    ]
  },
  identifiers={
    "id": "2",
  }
)

with open("path to file", "rb") as f:
  request.attach('receipt.pdf', f.read())

response = client.send_email(request)
print(response)

Running tests

Changes to the library can be tested by running make test from the parent directory.

Thanks!

• Dimitriy Narkevich for creating the library.
• EZL for contributing customer deletes and improving README
• Noemi Millman for adding custom JSON encoder
• Jason Kraus for event backfilling
• Nicolas Paris for better handling of NaN values