> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ecomail.cz/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an event

> Track a custom event for a subscriber. Supplements the JavaScript tracker.

Only the `email` field is required. All other fields (`category`, `action`, `label`, `property`, `value`) are optional — include only what makes sense for your use case.

The `value` field accepts a plain string, a JSON-encoded string, or a JSON object/array. If you pass an object or array, we will automatically JSON-encode it on our side.

<ParamField body="event" type="object" required>
  Event details.

  <Expandable title="event properties">
    <ParamField body="event.email" type="string" required>
      Subscriber's email address. The subscriber must already exist in your contact list.
    </ParamField>

    <ParamField body="event.category" type="string">
      Event category (e.g. `"shopping"`, `"engagement"`, `"support"`).
    </ParamField>

    <ParamField body="event.action" type="string">
      Event action (e.g. `"product_viewed"`, `"form_submitted"`, `"review_left"`).
    </ParamField>

    <ParamField body="event.label" type="string">
      Event label — a human-readable name or identifier (e.g. a product name, page title).
    </ParamField>

    <ParamField body="event.property" type="string">
      Event property — a custom key or identifier (e.g. a product SKU, category slug).
    </ParamField>

    <ParamField body="event.value" type="string | object | array">
      Event value. Can be a plain string, a JSON-encoded string, or a JSON object/array (objects and arrays will be JSON-encoded automatically on our side). Maximum length is **20,000 characters** (after JSON encoding, if applicable).
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api2.ecomailapp.cz/tracker/events \
    -H "key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "event": {
        "email": "john@example.com",
        "category": "shopping",
        "action": "product_viewed",
        "label": "Nike Air Max 90",
        "property": "nike-air-max-90",
        "value": {
          "product_id": 12345,
          "price": 139.99,
          "currency": "EUR",
          "variant": "Black/White",
          "url": "https://example.com/products/nike-air-max-90"
        }
      }
    }'
  ```

  ```php PHP theme={null}
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api2.ecomailapp.cz/tracker/events');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'key: YOUR_API_KEY',
      'Content-Type: application/json',
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'event' => [
          'email' => 'john@example.com',
          'category' => 'shopping',
          'action' => 'product_viewed',
          'label' => 'Nike Air Max 90',
          'property' => 'nike-air-max-90',
          'value' => [
              'product_id' => 12345,
              'price' => 139.99,
              'currency' => 'EUR',
              'variant' => 'Black/White',
              'url' => 'https://example.com/products/nike-air-max-90',
          ],
      ],
  ]));
  $response = curl_exec($ch);
  curl_close($ch);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": 1234,
    "email": "john@example.com",
    "category": "shopping",
    "action": "product_viewed",
    "label": "Nike Air Max 90",
    "property": "nike-air-max-90",
    "value": "{\"product_id\":12345,\"price\":139.99,\"currency\":\"EUR\",\"variant\":\"Black/White\",\"url\":\"https://example.com/products/nike-air-max-90\"}"
  }
  ```
</ResponseExample>