Custom Event Tracking
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/services/events/Events.java
- src/main/java/com/resend/services/events/model/Event.java
- src/main/java/com/resend/services/events/model/EventSummary.java
- src/main/java/com/resend/services/events/model/CreateEventOptions.java
- src/main/java/com/resend/services/events/model/UpdateEventOptions.java
- src/test/java/com/resend/services/events/EventsTest.java
- src/test/java/com/resend/services/util/EventsUtil.java
Custom Event Tracking allows you to define, manage, and trigger specific user actions within your application. The Events module provides the interface for creating event definitions with structured schemas and dispatching these events to contacts.
This module works in conjunction with other Resend services like Automations to trigger workflows based on event data.
Sources: src/main/java/com/resend/services/events/Events.java:13-16, src/test/java/com/resend/services/util/AutomationsUtil.java:16-18
Core Components
The Event Tracking system relies on several key models to define the structure and content of tracked data.
Event Definitions
An Event represents the full metadata of a tracked action. It includes a unique identifier, a descriptive name, and a schema defining the expected payload structure.
Sources: src/main/java/com/resend/services/events/model/Event.java:11-30
Event Schema
The schema is a Map<String, String> where keys represent the property names and values represent the data types (e.g., "string", "number"). This ensures that payloads sent during event triggering adhere to a predefined structure.
Sources: src/main/java/com/resend/services/events/model/CreateEventOptions.java:20-21, src/test/java/com/resend/services/util/EventsUtil.java:15-18
Class Relationship Diagram
The following diagram illustrates the relationship between the Events service and its associated data models.
This diagram shows the primary methods of the Events service and how they interact with option and result models.
Sources: src/main/java/com/resend/services/events/Events.java:36-105
Event Lifecycle Management
The Events class provides standard CRUD operations to manage the library of events available to your Resend account.
Event Management API
| Operation | Method | Endpoint | Description |
|---|---|---|---|
| Create | POST | /events | Defines a new event with a name and schema. |
| Get | GET | /events/{id} | Retrieves details of a specific event by ID or name. |
| List | GET | /events | Lists all defined events with optional pagination. |
| Update | PATCH | /events/{id} | Updates the schema of an existing event definition. |
| Remove | DELETE | /events/{id} | Deletes an event definition from the system. |
Sources: src/main/java/com/resend/services/events/Events.java:45-92
Management Flow
The following flowchart describes the typical process for preparing and using a custom event.
This diagram visualizes the flow from defining an event structure to utilizing it in active tracking.
Sources: src/test/java/com/resend/services/events/EventsTest.java:71-186, src/test/java/com/resend/services/util/EventsUtil.java:14-82
Dispatching Events
Sending an event associates an action with a specific contact and provides a payload containing the data defined in the event schema.
Sending Logic
To send an event, you must provide:
- Event Name: The identifier for the type of event (e.g., "user.signup").
- Contact Identification: Either a
contactIdor anemailto identify the recipient. - Payload: A
Map<String, Object>containing the actual data for this specific occurrence.
Sources: src/test/java/com/resend/services/util/EventsUtil.java:78-81, src/test/java/com/resend/services/events/EventsTest.java:178-199
Event Sending Sequence
The sequence below demonstrates the interaction between the SDK, the HTTP client, and the Resend API during an event dispatch.
This diagram represents the synchronous call flow for dispatching a custom event to a contact.
Sources: src/main/java/com/resend/services/events/Events.java:102-105, src/test/java/com/resend/services/events/EventsTest.java:178-186
Data Models
Event Schema Fields
The Event and EventSummary objects contain the following fields:
| Field | Type | Description |
|---|---|---|
id | String | Unique UUID for the event definition. |
name | String | Human-readable name used as an identifier. |
schema | Map<String, String> | Mapping of payload keys to their expected types. |
created_at | String | Timestamp when the event was first defined. |
updated_at | String | Timestamp of the last schema or name update. |
Sources: src/main/java/com/resend/services/events/model/Event.java:13-30, src/main/java/com/resend/services/events/model/EventSummary.java:13-27
CreateEventOptions Builder
Use the Builder pattern to construct event creation requests reliably.
// Example derived from EventsUtil.java
CreateEventOptions options = CreateEventOptions.builder()
.name("user.signup")
.addSchema("user_id", "string")
.addSchema("plan", "string")
.build();
Sources: src/main/java/com/resend/services/events/model/CreateEventOptions.java:68-98, src/test/java/com/resend/services/util/EventsUtil.java:14-21
Summary
Custom Event Tracking provides the foundation for behavioral messaging. By defining structured events and their schemas through the Events module, you enable your application to communicate specific user interactions back to Resend. This data can subsequently be used to power complex lifecycle marketing and automated communication workflows.