# Transactional Email UDR Report

This example retrieves transactional email Usage Detail Records (UDRs) for a given period. Each record covers the lifecycle from submission to final delivery status, including submission interface, processing metadata, routing, status codes, correlation IDs, message characteristics, and billing fields.

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

## Query

```graphql
query transactionalEmailUdrReport (
  $customerId: String!
  $filterEmail: TransactionalEmailColumnUdrFilters
  $datePeriod: DatePeriod!
  $pageIndex: Int
  $pageSize: Int
  $sort: SortDirection
) {
  transactionalEmailUdrReport(
    customerId: $customerId
    datePeriod: $datePeriod
    filter: $filterEmail
    page: $pageIndex
    size: $pageSize
    sort: $sort
  ) {
    content {
      metaId
      metaVersion
      metaCreationTime
      customerId
      metaEntryInterface
      metaProcessingDomain
      metaDataCenter
      metaEnvironment
      jobId
      costCenter
      userId
      campaign
      usageId
      usageType
      usageCreationTime
      usageMsgFrom
      usageMsgFromDomain
      usageMsgTo
      usageMsgToDomain
      usageMsgSize
      usageSizeUnit
      usageStatus
      usageSubStatus
      usageStatusDetails
      usageStatusCode
      usageReference
      usageCorrelationId
    }
    pageIndex
    pageSize
    hasMoreElements
  }
}
```

## Variables

```json
{
	"customerId": "XXXXX",
	"datePeriod": {
		"fromIncluded": "2025-06-04T08:00:00.000Z",
		"toExcluded": "2025-06-04T08:54:00.000Z"
	},
	"filterEmail": {
		"usageStatus": { "values": ["OK"] },
		"usageStatusCode": { "values": ["250"] },
		"usageSubStatus": { "notValues": ["BOUNCED", "DEFERRED"] }
	},
	"pageIndex": 0,
	"pageSize": 3,
	"sort": "ASC"
}
```

> **Filter**  This report can be filtered by `usageStatus`, `usageSubStatus`, and `usageStatusCode` (shown above as response fields), as well as `usageId`, `usageType`, and `userId`. The `filterEmail` value above returns delivered mail (`usageStatus` = `OK`, `usageStatusCode` = `250`) while excluding bounced and deferred records. See [Filtering](/common/graphql-examples#filtering) for how `values` (logical OR) and `notValues` (logical AND NOT) combine.


## Response

```json
{
	"data": {
		"transactionalEmailUdrReport": {
			"content": [
				{
					"metaId": "70cb3364-979f-4192-811c-8fa3ccaa658c",
					"metaVersion": 1,
					"metaCreationTime": "2025-06-04T08:00:15.803Z",
					"customerId": "XXXXX",
					"metaEntryInterface": "smtp",
					"metaProcessingDomain": "de",
					"metaDataCenter": "xxxxxx",
					"metaEnvironment": "de.xxxxxx.transactional-email",
					"jobId": "a296e0e5-0652-4c94-8aab-5b3290d4d607",
					"costCenter": null,
					"userId": "XXXXX_Retarus",
					"campaign": null,
					"usageId": "a296e0e5-0652-4c94-8abb-5b3270d4e607#00000000#1",
					"usageType": "mail",
					"usageCreationTime": "2025-06-04T08:00:06.178Z",
					"usageMsgFrom": "xxxxxx@retarus.de",
					"usageMsgFromDomain": "retarus.de",
					"usageMsgTo": "recipient@example.com",
					"usageMsgToDomain": "example.com",
					"usageMsgSize": 60036,
					"usageSizeUnit": "byte",
					"usageStatus": "OK",
					"usageSubStatus": "DELIVERED",
					"usageStatusDetails": "DELIVERED (OK): mail delivered",
					"usageStatusCode": "250",
					"usageReference": null,
					"usageCorrelationId": "a296j0e5-0652-4c94-8abb-5b4290s4e607#00000000#1"
				}
				// more items ...
			],
			"pageIndex": 0,
			"pageSize": 3,
			"hasMoreElements": true
		}
	}
}
```

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


## Field reference

| **Field** | **Description** |
|  --- | --- |
| `metaId` | Unique metadata identifier for this email record |
| `metaVersion` | Schema version number of this record |
| `metaCreationTime` | UTC timestamp when the usage/metadata record was created in the system |
| `customerId` | Retarus customer account identifier |
| `metaEntryInterface` | Submission method used |
| `metaProcessingDomain` | Geographic processing domain/region |
| `metaDataCenter` | Data center where the email was processed |
| `metaEnvironment` | Full processing environment identifier |
| `jobId` | Unique identifier for the email job |
| `costCenter` | Cost center for billing (null if not specified) |
| `userId` | User account identifier used for submission |
| `campaign` | Marketing campaign identifier (null if not specified) |
| `usageId` | Unique usage record identifier |
| `usageType` | Type of usage record (mail, bounce, etc.) |
| `usageCreationTime` | UTC timestamp when email usage processing was initiated |
| `usageMsgFrom` | Sender email address |
| `usageMsgFromDomain` | Domain portion of the sender email address |
| `usageMsgTo` | Recipient email address |
| `usageMsgToDomain` | Domain portion of the recipient email address |
| `usageMsgSize` | Total message size including headers and content |
| `usageSizeUnit` | Measurement units for `usageMsgSize` |
| `usageStatus` | High-level delivery status |
| `usageSubStatus` | Detailed delivery status |
| `usageStatusDetails` | Human-readable detailed status description |
| `usageStatusCode` | SMTP status code associated with the final state |
| `usageReference` | Customer-provided reference |
| `usageCorrelationId` | Correlation identifier for end-to-end tracking across systems |