# Transactional Email Event Report

This example retrieves transactional email engagement event records for a given period. Each record reflects a recipient interaction (e.g., open, click, bounce, unsubscribe) and includes client/device metadata, campaign context, and a link back to the original delivery.

For complete field definitions and advanced options, see the [GraphQL API Reference](https://developers.retarus.com/common/sdl).

## Query

```graphql
query transactionalEmailEventReport (
  $customerId: String!
  $filterEvent: TransactionalEmailColumnEventFilters
  $datePeriod: DatePeriod!
  $pageIndex: Int
  $pageSize: Int
  $sort: SortDirection
) {
  transactionalEmailEventReport(
    customerId: $customerId
    datePeriod: $datePeriod
    filter: $filterEvent
    page: $pageIndex
    size: $pageSize
    sort: $sort
  ) {
    content {
      eventId
    dataCenter
    customerId
    userId
    usageId
    usageMsgFrom
    usageMsgFromDomain
    usageMsgTo
    usageMsgToDomain
    costCenter
    campaign
    eventTime
    eventType
    eventSubType
    eventClickUrl
    eventClientName
    eventClientVersion
    eventClientIsMail
    eventUserAgent
    eventOsName
    eventOsVersion
    reference
    }
    pageIndex
    pageSize
    hasMoreElements
  }
}
```

## Variables

```json
{
	"customerId": "XXXXX",
	"datePeriod": {
		"fromIncluded": "2025-06-05T00:00:00.000Z",
		"toExcluded": "2025-07-07T10:00:00.000Z"
	},
	"filterEvent": {
		"eventType": { "values": ["OPEN", "CLICK"] },
		"userId": { "notValues": ["SYSTEM_ACCOUNT"] }
	},
	"pageIndex": 0,
	"pageSize": 3,
	"sort": "ASC"
}
```

> **Filter**  The `filterEvent` value above keeps only open and click events (`eventType`) and excludes a system account (`userId`). Available filter fields are `eventType`, `eventSubType`, `usageId`, and `userId`. See [Filtering](/common/graphql-examples#filtering) for how `values` (logical OR) and `notValues` (logical AND NOT) combine.


## Response

```json
{
	"data": {
		"transactionalEmailEventReport": {
			"content": [
				{
          "eventId": "b0fd34e4-8e34-430e-a4ca-96f3d70448d7",
          "dataCenter": "fraix1",
          "customerId": "XXXXX",
          "userId": "XXXXX_Retarus",
          "usageId": "b0fd34e4-8e34-430e-a4ca-96f3d70448d7#329a85ae#d6ede1ff",
          "usageMsgFrom": "message_from@example.com",
          "usageMsgFromDomain": "example.com",
          "usageMsgTo": "message_tog@example.com",
          "usageMsgToDomain": "example.com",
          "costCenter": "1234",
          "campaign": "1234",
          "eventTime": "2025-07-14T13:54:23.038Z",
          "eventType": "OPEN",
          "eventSubType": "MAIL_OPENED",
          "eventClickUrl": null,
          "eventClientName": "Outlook",
          "eventClientVersion": "2016",
          "eventClientIsMail": true,
          "eventUserAgent": "Mozilla/4.0 (compatible; ms-office; MSOffice 16)",
          "eventOsName": "Other",
          "eventOsVersion": "Unknown",
          "reference": "1234"
        },
				// more items ...
			],
			"pageIndex": 0,
			"pageSize": 3,
			"hasMoreElements": true
		}
	}
}
```

> **Note**  Additional records (up to the requested `pageSize`) are omitted for brevity.


## Field reference

| **Field** | **Description** |
|  --- | --- |
| `eventId` | Unique identifier for the engagement event |
| `dataCenter` | Data center where the event was processed |
| `customerId` | Retarus customer account identifier |
| `userId` | User account identifier associated  with the original email |
| `usageId` | Unique usage record identifier linking to the original email delivery |
| `usageMsgFrom` | Original sender email address from the delivered message |
| `usageMsgFromDomain` | Domain portion of the original sender email address |
| `usageMsgTo` | Original recipient email address from the delivered message |
| `usageMsgToDomain` | Domain portion of the original recipient email address |
| `costCenter` | Cost center for billing (null if not specified) |
| `campaign` | Marketing campaign identifier |
| `eventTime` | UTC timestamp when the engagement event occurred |
| `eventType` | High-level event category |
| `eventSubType` | Detailed event specification |
| `eventClickUrl` | Full URL that was clicked (null for non-click events) |
| `eventClientName` | Email client or application name |
| `eventClientVersion` | Email client/application version |
| `eventClientIsMail` | Whether the client is a dedicated mail application |
| `eventUserAgent` | Full user agent string captured for the event |
| `eventOsName` | Operating system name |
| `eventOsVersion` | Operating system version |
| `reference` | Customer-provided reference for tracking purposes |