Python Server SDK

The ChimeKit Python SDK provides a Pythonic way to interact with the ChimeKit API from your server-side applications. It handles authentication, request formatting, and response parsing with full type hints.

All endpoints in this reference are rooted at /sdk/v1 and require an Authorization: Bearer {token} header. The SDK signs this token for you.

Install

pip install chimekit

Audience

Audience endpoints let you identify members, update profiles, and manage channel suppressions.

POST/sdk/v1/audience/identify

Identify an audience member

Identify creates (or updates) an audience member by externalUserId. This is the canonical way to upsert profiles before sending messages or running workflows.

Required attributes

Name
externalUserId
Type
string
Description
Your system's stable identifier for the end user.

Optional attributes

Name
displayName
Type
string
Description
A human-friendly name for the member.
Name
attributes
Type
object
Description
Arbitrary JSON attributes to attach to the member.
Name
identities
Type
array
Description
Channel identities for the member. Currently supports email identities.

Request

POST

/sdk/v1/audience/identify

import os
from chimekit import ChimeKit

ck = ChimeKit(secret_key=os.environ["CHIMEKIT_SECRET_KEY"])

member = ck.identify(
    "user_123",
    {
        "displayName": "Ava Example",
        "identities": [
            {"type": "email", "value": "ava@example.com", "verified": True}
        ],
        "attributes": {"plan": "pro"},
    },
)

Response

{
  "member": {
    "id": "user_123",
    "email": "ava@example.com",
    "displayName": "Ava Example",
    "identities": [{ "type": "email", "value": "ava@example.com", "verified": true }],
    "attributes": { "plan": "pro" },
    "created": "2025-01-01T00:00:00.000Z",
    "updated": "2025-01-01T00:00:00.000Z",
    "deleted": null,
    "lastSeen": null
  }
}

GET/sdk/v1/audience/members/:externalUserId

Get an audience member

Returns the member profile for the provided externalUserId, or null if no active member exists.

Path parameters

Name
externalUserId
Type
string
Description
The member's external identifier.

Request

GET

/sdk/v1/audience/members/:externalUserId

member = ck.audience.find_member("user_123")

Response

{
  "member": {
    "id": "user_123",
    "email": "ava@example.com",
    "displayName": "Ava Example",
    "identities": [{ "type": "email", "value": "ava@example.com", "verified": true }],
    "attributes": { "plan": "pro" },
    "created": "2025-01-01T00:00:00.000Z",
    "updated": "2025-01-01T00:00:00.000Z",
    "deleted": null,
    "lastSeen": null
  }
}

PUT/sdk/v1/audience/members/:externalUserId

Update an audience member

Updates an existing member. If the member does not exist, the response is { "member": null }.

Path parameters

Name
externalUserId
Type
string
Description
The member's external identifier.

Optional attributes

Name
displayName
Type
string
Description
Updates the member's display name.
Name
attributes
Type
object
Description
Replaces the member's attribute object.
Name
identities
Type
array
Description
Replaces the member's identities array (email identities are supported).

Request

PUT

/sdk/v1/audience/members/:externalUserId

updated = ck.audience.update_member(
    "user_123",
    {
        "displayName": "Ava Example (Updated)",
        "attributes": {"plan": "enterprise"},
    },
)

Response

{
  "member": {
    "id": "user_123",
    "email": "ava@example.com",
    "displayName": "Ava Example (Updated)",
    "identities": [{ "type": "email", "value": "ava@example.com", "verified": true }],
    "attributes": { "plan": "enterprise" },
    "created": "2025-01-01T00:00:00.000Z",
    "updated": "2025-01-02T00:00:00.000Z",
    "deleted": null,
    "lastSeen": null
  }
}

DELETE/sdk/v1/audience/members/:externalUserId

Delete an audience member

Soft-deletes an audience member by externalUserId. If the member does not exist, id will be null.

Path parameters

Name
externalUserId
Type
string
Description
The member's external identifier.

Request

DELETE

/sdk/v1/audience/members/:externalUserId

deleted_id = ck.audience.delete_member("user_123")

Response

{ "id": "user_123" }

GET/sdk/v1/audience/members/:externalUserId/suppressions

List member suppressions

Lists suppressions for a member. Suppressions prevent delivery for a specific identity, optionally scoped to a category.

Path parameters

Name
externalUserId
Type
string
Description
The member's external identifier.

Request

GET

/sdk/v1/audience/members/:externalUserId/suppressions

suppressions = ck.audience.list_suppressions("user_123")

Response

{
  "suppressions": [
    {
      "id": "sup_123",
      "reason": "opt-out",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z",
      "identity": {
        "id": "aid_123",
        "type": "email",
        "value": "ava@example.com",
        "verified": true,
        "metadata": null
      },
      "category": null
    }
  ]
}

POST/sdk/v1/audience/members/:externalUserId/suppressions

Add a member suppression

Creates a suppression for a specific identity. If categoryId is omitted, the suppression is global for that identity.

Path parameters

Name
externalUserId
Type
string
Description
The member's external identifier.

Required attributes

Name
identity
Type
object
Description
The identity to suppress. Must include type and value (email identities are supported).

Optional attributes

Name
categoryId
Type
string
Description
If set, suppresses only for a specific category. If omitted, suppression is global.

Request

POST

/sdk/v1/audience/members/:externalUserId/suppressions

suppression = ck.audience.suppress(
    "user_123",
    identity={"type": "email", "value": "ava@example.com"},
)

Response

{
  "suppression": {
    "id": "sup_123",
    "reason": "opt-out",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z",
    "identity": {
      "id": "aid_123",
      "type": "email",
      "value": "ava@example.com",
      "verified": true,
      "metadata": null
    },
    "category": null
  }
}

DELETE/sdk/v1/audience/members/:externalUserId/suppressions/:suppressionId

Remove a member suppression

Removes a suppression by id. The response body is empty on success.

Path parameters

Name
externalUserId
Type
string
Description
The member's external identifier.
Name
suppressionId
Type
string
Description
The suppression identifier.

Request

DELETE

/sdk/v1/audience/members/:externalUserId/suppressions/:suppressionId

ck.audience.remove_suppression("user_123", "sup_123")

Response

null

Messages

Message endpoints let you send messages, fetch message detail, and list recent activity for a member.

POST/sdk/v1/messages/send

Send a message

Sends a message to an audience member.

Content can be provided in one of two ways:

A top-level content.templateId (send a template as-is, with optional variables), or
One or more channels (content.in_app and/or content.email).

Required attributes

Name
externalUserId
Type
string
Description
The audience member's external identifier.
Name
content
Type
object
Description
Message content definition (template or channels).

`content` (template)

Name
content.templateId
Type
string
Description
Template id to send.
Name
content.variables
Type
object
Description
Variables to resolve in the template.

`content` (channels)

Name
content.in_app
Type
object
Description
In-app content definition (manual or template reference).
Name
content.email
Type
object
Description
Email content definition (manual).
Name
content.variables
Type
object
Description
Base variables merged into channel variables.

Request

POST

/sdk/v1/messages/send

result = ck.messages.send_message(
    "user_123",
    {
        "content": {
            "in_app": {
                "title": "Welcome!",
                "snippet": "A quick hello from ChimeKit",
                "body": "Sent from the SDK endpoints.",
            }
        }
    },
)

Response

{
  "message": {
    "id": "msg_123",
    "memberId": "mem_123",
    "categoryId": "cat_123",
    "source": "sdk",
    "templateId": null,
    "templateVersionId": null,
    "payload": {},
    "dispatchStatus": "dispatched",
    "scheduledFor": null,
    "createdAt": "2025-01-01T00:00:00.000Z"
  },
  "delivery": null,
  "notification": {
    "id": "not_123",
    "title": "Welcome!",
    "snippet": "A quick hello from ChimeKit",
    "body": "Sent from the SDK endpoints.",
    "actions": null,
    "readAt": null,
    "archivedAt": null
  },
  "audienceMember": {
    "id": "mem_123"
  }
}

GET/sdk/v1/messages/:messageId

Get a message

Fetches a message by id, including delivery + notification details when available.

Path parameters

Name
messageId
Type
string
Description
The message identifier.

Request

GET

/sdk/v1/messages/:messageId

detail = ck.messages.get_message("msg_123")

Response

{
  "message": {
    "message": {
      "id": "msg_123",
      "memberId": "mem_123",
      "categoryId": "cat_123",
      "source": "sdk",
      "templateId": null,
      "templateVersionId": null,
      "payload": {},
      "dispatchStatus": "dispatched",
      "scheduledFor": null,
      "createdAt": "2025-01-01T00:00:00.000Z"
    },
    "delivery": null,
    "notification": {
      "id": "not_123",
      "title": "Welcome!",
      "snippet": "A quick hello from ChimeKit",
      "body": "Sent from the SDK endpoints.",
      "actions": null,
      "readAt": null,
      "archivedAt": null
    },
    "recipient": {
      "id": "mem_123",
      "externalUserId": "user_123",
      "displayName": "Ava Example",
      "email": "ava@example.com"
    }
  }
}

GET/sdk/v1/messages/members/:externalUserId/messages

List messages for a member

Lists recent message activity for a member.

Path parameters

Name
externalUserId
Type
string
Description
The audience member's external identifier.

Optional query parameters

Name
limit
Type
integer
Description
Number of items to return (min 1, max 100). Defaults to 20.
Name
offset
Type
integer
Description
Number of items to skip. Defaults to 0.

Request

GET

/sdk/v1/messages/members/:externalUserId/messages

result = ck.messages.list_messages_for_user(
    "user_123",
    {"limit": 20, "offset": 0},
)
messages = result["messages"]
pagination = result["pagination"]

Response

{
  "messages": [
    {
      "message": {
        "id": "msg_123",
        "memberId": "mem_123",
        "categoryId": "cat_123",
        "source": "sdk",
        "dispatchStatus": "dispatched",
        "scheduledFor": null,
        "createdAt": "2025-01-01T00:00:00.000Z",
        "snippet": "A quick hello from ChimeKit"
      },
      "delivery": null,
      "recipient": {
        "id": "mem_123",
        "externalUserId": "user_123",
        "displayName": "Ava Example",
        "email": "ava@example.com"
      },
      "category": {
        "id": "cat_123",
        "name": "Product"
      }
    }
  ],
  "pagination": { "totalCount": 1, "limit": 20, "offset": 0 }
}

Workflows

Workflow endpoints let you run a workflow for a member and query run status.

POST/sdk/v1/workflows/:key/run

Run a workflow

Queues a workflow run for an existing audience member.

Path parameters

Name
key
Type
string
Description
The workflow key to run.

Required attributes

Name
externalUserId
Type
string
Description
The audience member's external identifier.

Optional attributes

Name
context
Type
object
Description
Arbitrary JSON context merged into the workflow run context.

Request

POST

/sdk/v1/workflows/:key/run

run = ck.workflow.run(
    "welcome-sequence",
    {"externalUserId": "user_123", "context": {"utmCampaign": "winter-launch"}},
)

Response

{ "runId": "wr_123", "status": "queued" }

GET/sdk/v1/workflows/runs/:runId

Get a workflow run

Returns workflow run metadata for a previously queued run.

Path parameters

Name
runId
Type
string
Description
The workflow run identifier.

Request

GET

/sdk/v1/workflows/runs/:runId

run = ck.workflow.get_run("wr_123")

Response

{
  "run": {
    "id": "wr_123",
    "workflowVersionId": "wv_123",
    "workflowId": "w_123",
    "workflowKey": "welcome-sequence",
    "status": "queued",
    "memberId": "mem_123",
    "memberExternalUserId": "user_123",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "startedAt": null,
    "finishedAt": null,
    "context": { "utmCampaign": "winter-launch", "apiKeyId": "key_123" }
  }
}

Python Server SDK

Install

Required attributes

Optional attributes

Request

Response

Path parameters

Request

Response

Path parameters

Optional attributes

Request

Response

Path parameters

Request

Response

Path parameters

Request

Response

Path parameters

Required attributes

Optional attributes

Request

Response

Path parameters

Request

Response

Required attributes

content (template)

content (channels)

Request

Response

Path parameters

Request

Response

Path parameters

Optional query parameters

Request

Response

Path parameters

Required attributes

Optional attributes

Request

Response

Path parameters

Request

Response

`content` (template)

`content` (channels)