Query contact events

Returns the events of the given contacts for a single event name, using
cursor paging.

Filtering:
contactIDs (1-100) names the contacts to read, and eventName selects the
event, returning every origin the brand has data for, limited to Omnisend's
standard events. eventOrigin narrows the result to a single origin, and
from/to define a begin-inclusive, end-exclusive time window.

Supported events:
eventName accepts one of the standard events below; brand-custom events
are not readable.

  • subscribed to marketing
  • unsubscribed from marketing
  • opted-in for promotions
  • opted-out from promotions
  • message sent
  • opened message
  • clicked message
  • marked message as spam
  • message delivery failed

Paging:
limit (1-1000, default 100) caps the page size. after continues a previous
page and must be sent with the same filters that page was read with.
Results are grouped per contact, and per origin within a contact, and are
ordered newest first inside such a group rather than across the page.
Paging is forward-only, so paging.cursors.after is null on the last page.

Scopes:
events.read

Rate Limiting:
This endpoint is rate limited to 20 requests per minute.

Body Params

Filters and paging parameters

Request body for POST /events/query.

string

Cursor from the previous page, sent together with that page's filters.

contactIDs
array of strings
required
length between 1 and 100

Contacts to read the events of: 24-character hex contact IDs.

contactIDs*
string
required

Event name to query.

string

Narrows the result to a single event origin.

string

Inclusive start of the time window (RFC 3339).

integer
1 to 1000

Page size (1-1000, default 100).

string

Exclusive end of the time window (RFC 3339).

Headers
string
required
Defaults to 2026-preview

API version that specifies the response format and behaviour

Responses

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json