Track event
Track an event for a contact. Automatically creates or upserts the contact, then records the event. Tracked events can be used as workflow triggers, segment filters, and audience filters.
Reserved event names (rejected with VALIDATION_ERROR and code reserved_event): anything matching email.*, contact.subscribed, contact.unsubscribed, segment.<slug>.entry, segment.<slug>.exit. These are emitted by Bitelio itself.
Idempotency: re-tracking the same event creates a new event record. Send an Idempotency-Key header to have a repeated request refused with 409 instead.
Authorization
ApiKeyAuth API Key authentication. Secret keys (sk_*) are required for all endpoints except /v1/track. Public keys (pk_*) only work with the /v1/track endpoint for client-side event tracking. The project is automatically derived from the key.
In: header
Header Parameters
Optional key that guarantees this request runs at most once. If the key was already used by your project, the request is refused with 409 instead of being performed a second time. Keys are scoped to your project, expire after 24 hours (configurable when self-hosting), and must be 1-255 printable ASCII characters.
length <= 255Request Body
application/json
Contact email. The contact is auto-created if it doesn't exist.
emailEvent name. Cannot match the reserved patterns above.
Subscription state to apply to the contact. New contacts default to subscribed (true). Existing contacts keep their current state unless you pass an explicit value here. Pass false to track an event without resubscribing an unsubscribed contact.
Contact data and one-off event variables. Persistent values (primitives, plain objects) are saved on the contact and become available as template variables. Pass { value, persistent: false } for one-shot variables that should not be stored on the contact (e.g. order IDs, transaction details). null deletes a field. Empty strings are ignored. Reserved keys are filtered out — see the contacts concept page.
Response Body
application/json
application/json
curl -X POST "https://api.bitelio.com/v1/track" \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "event": "purchase", "data": { "product": "Premium Plan", "amount": 99 } }'{
"success": true,
"data": {
"contact": "string",
"event": "string",
"timestamp": "2019-08-24T14:15:22Z"
}
}{
"success": false,
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "Idempotency-Key \"order-1234-receipt\" has already been used",
"statusCode": 409,
"requestId": "8f14e45f-ceea-467a-9575-1f0f38e0b1c2",
"details": {
"key": "order-1234-receipt",
"originalRequest": "POST /v1/send",
"originalRequestAt": "2025-01-15T10:30:00.000Z",
"originalStatusCode": 200
},
"suggestion": "This Idempotency-Key was already used, so the request was refused rather than performed twice. Generate a new key for a genuinely new request."
},
"timestamp": "2025-01-15T10:31:00.000Z"
}