---
title: "Events API"
description: "Events in the OneSend API: 2 endpoints. Custom events from your app (POST /v1/events/track) that start automations, reach goals and continue waiting runs."
url: https://onesend.email/docs/api-reference/events/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Events

Custom events from your app (`POST /v1/events/track`) that start automations, reach goals and continue waiting runs.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## 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

application/json, required.

| Field | Type | Description |
|---|---|---|
| `email` | `string (email)` |  |
| `contactId` | `string` |  |
| `name`required | `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

`202` Success

```
{
  "id": string,
  "object": "event",
  "name": string,
  "contactId": string,
  "properties": object,
  "occurredAt": string,
  "duplicate": boolean
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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

`200` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
