---
title: "Track a custom event for a contact"
method: POST
path: "/api/track"
tags: ["Events"]
---

# Track a custom event for a contact

`POST /api/track`

## Request

- Base URL: `https://api.sendly.now`
- URL: `https://api.sendly.now/api/track`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.sendly.now/api/auth/oauth2/authorize`, token URL `https://app.sendly.now/api/auth/oauth2/token`, scopes: `events:write`)

Record a custom event, creating or updating the contact by email as a side effect. Requires a FULL (`sk_*`) key — SENDING_ONLY (`pk_*`) keys answer 403, since recording events is not sending mail. Reserved system event names (`email.*`, `contact.subscribed`/`unsubscribed`, `segment.*.entry`/`.exit`) are rejected.

Requires the `events:write` scope — Record custom events for your contacts.

## Request body

- TrackEvent: Body for POST /api/track — record a custom event for a contact.
  - `data` object: Arbitrary JSON value (string, number, boolean, null, array, or object).
  - `email` string, email, required
  - `event` string, required
  - `subscribed` boolean

## Response `200`

Event tracked

- TrackEventResponse: Response from POST /api/track.
  - `data` object, required
    - `contact` string, uuid, required
    - `event` string, uuid, required
    - `timestamp` string, date-time, required: ISO 8601 datetime string
  - `success` true, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized — missing or invalid auth
- `403`: Forbidden — insufficient permissions or project disabled
- `429`: Rate limit or billing limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/sendly/apis/sendly-api.md) · [All operations](https://skmtc.dev/sendly/apis/sendly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sendly/apis/sendly-api/revisions/ce7cfb7f7c7e?raw)