Events

Intro

Endpoint: https://api.omnisend.com/api/events

Guide: How to send events using Events API

Send customer events to Omnisend to track behavior and trigger automations. Events can be recommended (predefined e-commerce actions) or custom (user-defined for flexible tracking).

Event Types

For a full list of recommended events and their schemas, see the Events Overview.

Version and Origin

Every event requires origin and recommended events require eventVersion. Incorrect values can cause issues with automations, segmentation, and reporting.

Note: If you are an e-commerce platform building an integration, contact Omnisend for origin guidance.

Event Deduplication

To avoid processing duplicate events, include both eventID and eventTime in the payload. Events with the same eventID and eventTime are processed only once.

Warning: Deduplication works only for historical events. It does not apply to real-time events used for automations.

Example: Send a custom event

curl --request POST \
     --url https://api.omnisend.com/api/events \
     --header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
     --header 'Omnisend-Version: 2026-preview' \
     --header 'Content-Type: application/json' \
     --data '{
  "eventName": "my custom event",
  "origin": "api",
  "contact": {
    "email": "[email protected]"
  },
  "properties": {
    "customField": "value"
  }
}'

Example: Send a recommended event

curl --request POST \
     --url https://api.omnisend.com/api/events \
     --header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
     --header 'Omnisend-Version: 2026-preview' \
     --header 'Content-Type: application/json' \
     --data '{
  "eventName": "added product to cart",
  "origin": "api",
  "eventVersion": "",
  "eventID": "f3f61bc6-07b8-4645-92d8-189d882dbcb1",
  "eventTime": "2024-07-01T12:00:00Z",
  "contact": {
    "email": "[email protected]"
  },
  "properties": {
    "abandonedCheckoutURL": "https://example.com/checkout",
    "cartID": "cart-123",
    "currency": "USD",
    "lineItems": [
      {
        "productID": "prod-1",
        "productTitle": "Running Shoes",
        "productPrice": 79.99,
        "productQuantity": 1,
        "productURL": "https://example.com/products/running-shoes",
        "productImageURL": "https://example.com/images/running-shoes.jpg"
      }
    ],
    "value": 79.99
  }
}'

For the full list of properties for each recommended event, see the individual event pages linked from the Events Overview.

Reading events

Endpoint: https://api.omnisend.com/api/events/query

Read the events collected for up to 100 contacts at a time. contactIDs and eventName are required, so every request targets one event of a known set of contacts. Only Omnisend's recommended events can be read; custom events are not returned.

Results are grouped per contact, and per origin within a contact, newest first inside such a group rather than across the whole page.

Paging is forward-only. Send after together with the same filters the previous page was read with, and stop once paging.cursors.after is null.

OAuth apps need the events.read scope for this endpoint.

Example: Read events of a contact

curl --request POST \
     --url https://api.omnisend.com/api/events/query \
     --header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
     --header 'Omnisend-Version: 2026-preview' \
     --header 'Content-Type: application/json' \
     --data '{
  "contactIDs": ["6a7c31f0d4b28e5a9c14f3b7"],
  "eventName": "placed order",
  "from": "2026-07-09T00:00:00Z",
  "to": "2026-07-16T00:00:00Z",
  "limit": 100
}'

Reading event property values

Endpoint: https://api.omnisend.com/api/events/property-values/query

Read the distinct values a brand's events hold for given event properties, for example every currency
a placed order was made in. Use it to build segment and report filters without reading whole events
and deriving the values yourself.

Values come back as strings grouped under the property path they were requested with, ordered
alphabetically within a group. They all belong to the origin the request named, which the response
echoes back as eventOrigin.

A property path that holds no values is still part of the response, with an empty array. An unknown
path is therefore not an error: it reads as a path nothing was collected for.

Paging is forward-only. Send after together with the same filters the previous page was read with —
only limit may change — and stop once paging.cursors.after is null.

OAuth apps need the events.read scope for this endpoint. It allows 20 requests per minute.

Example: Read the values of event properties

curl --request POST \
     --url https://api.omnisend.com/api/events/property-values/query \
     --header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
     --header 'Omnisend-Version: 2026-preview' \
     --header 'Content-Type: application/json' \
     --data '{
  "eventName": "placed order",
  "eventOrigin": "api",
  "properties": ["currency", "lineItems.productTitle"],
  "limit": 100
}'

{
  "eventName": "placed order",
  "eventOrigin": "api",
  "properties": {
    "currency": ["EUR", "USD"],
    "lineItems.productTitle": ["Running Shoes"]
  },
  "paging": {
    "limit": 100,
    "hasMore": false,
    "cursors": {
      "after": null
    }
  }
}

See Also

• Events Overview
• How to send custom events to trigger custom automations
• Errors & responses