Events
Custom events from your app (POST /v1/events/track) that start automations, reach goals and continue waiting runs.
Track a custom event
POST /v1/events/track
Records something a contact did in your app, such as cart_abandoned or order_completed. Events start automations with an event trigger, end runs whose goal is the event, and continue runs waiting for it. Properties are available in automation emails as {{event.<name>}}. A Sending only key is enough. Identify the contact by email or contactId; unknown addresses return 404 unless createContact is true. Events sent with a test-mode key are stored but start no automation.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
email | string (email) | |
contactId | string | |
namerequired | string | Event name, for example cart_abandoned or order_completed. |
properties | object | Up to 16 KB of JSON. Available in templates as {{event.<name>}}. |
occurredAt | string | |
idempotencyKey | string | A retry with the same key is recorded once. |
createContact | boolean | Create the contact (status subscribed) when no contact has this email. Default false: unknown addresses return 404. |
Responses
{
"id": string,
"object": "event",
"name": string,
"contactId": string,
"properties": object,
"occurredAt": string,
"duplicate": boolean
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
List tracked events
GET /v1/events/tracked
Custom events, newest first. Filter by contactId and name.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | |
limit | query | integer | Default 50. 1 to 200. |
contactId | query | string | |
name | query | string |
Responses
{
"data": [{
"id": string,
"object": "event",
"name": string,
"contactId": string,
"properties": object,
"occurredAt": string,
"duplicate": boolean
}],
"nextCursor": string or null
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)