Report Message Events

[POST] /api/v2/embedded-messages/report-events

This endpoint is used to report one or more user engagement events, such as when a message is read, clicked, or deleted.

Query Parameters

  • tenantId (integer, required): Your tenant ID.
  • brandId (string, required): The ID of the specific brand you are targeting.

Request Body

The request body should be a JSON array of one or more event objects. Each object has the following properties:

  • timestamp (string, required): The UTC timestamp for when the event occurred, in ISO 8601 format.
  • uuid (string, required): A unique identifier for this event.
  • eventType (string, required): The type of event being reported. See the list of available event types below.
  • customerId (string, conditional): The ID for a known customer. One of customerId or visitorId must be provided.
  • visitorId (string, conditional): The ID for an anonymous visitor. One of customerId or visitorId must be provided.
  • context (object, required): An object containing additional data specific to the event type. See the context object structure below.

Event Types

The following values are currently supported for the eventType field:

  • embedded-message.read
  • embedded-message.unread
  • embedded-message.clicked
  • embedded-message.deleted

Context Object

For all current event types, the context object requires the following properties:

  • messageId (string): The unique ID of the message the event relates to.
  • containerId (string): The ID of the container the message belongs to.

Example Request Body

This example shows how to report a single read event.

[
	{
    "timestamp": "2025-07-03T07:35:01.869Z",
    "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "eventType": "embedded-message.read",
    "customerId": "opt__001",
    "context": {
	    "messageId": "60808861-5cb7-4f76-b8f9-dc80b5b842ef",
	    "containerId": "Inbox"
    }
  }
]

Responses

204 No Content - Success

If the event data is valid and successfully processed, the API will return a 204 No Content status with an empty body.

Rate Limit

This endpoint is subject to the general API rate limit of 50 requests per 10 seconds. Learn more about handling rate limits.