Events API

Relevant source files

The following files were used as context for generating this wiki page:

• events.go
• examples/events.go
• events_test.go
• examples/automations.go
• errors.go
• webhooks.go

The Events API manages custom event definitions and triggers. It allows you to define data schemas for specific actions, such as user registrations or order placements, and send those events to Resend.

Sending an event triggers configured Automations within the Resend platform. The API supports defining property types, updating schemas, and retrieving event summaries or detailed logs.

Sources: events.go:193-207, examples/events.go:101-115, examples/automations.go:138-164

Architecture and Data Structures

The Events API architecture relies on the EventsSvc interface and its implementation EventsSvcImpl. This service communicates with the Resend API using standard HTTP methods.

Data Models

The system uses several structures to define events and their payloads.

Structure	Purpose	Key Fields
Event	Represents a full event definition.	Id, Name, Schema, CreatedAt
CreateEventRequest	Parameters for creating an event.	Name, Schema
SendEventRequest	Parameters for triggering an event.	Event, ContactId, Email, Payload
EventSummary	Brief version of an event for lists.	Id, Name, CreatedAt

Sources: events.go:21-69

Event Schema Types

Schemas define the data types allowed in event payloads. The API provides constant string identifiers for these types.

Constant	Value	Description
EventSchemaTypeString	"string"	Represents textual data.
EventSchemaTypeNumber	"number"	Represents numerical data.
EventSchemaTypeBoolean	"boolean"	Represents true/false values.
EventSchemaTypeDate	"date"	Represents date/time values.

Sources: events.go:9-14

Logic and Data Flow

The following diagram illustrates the flow of creating an event definition and subsequently sending an event instance to trigger automations.

This diagram shows the relationship between defining an event and using it to trigger backend workflows.
Sources: events.go:76-89, events.go:193-207, examples/automations.go:37-64

Lifecycle Management

The EventsSvc provides methods for the entire lifecycle of an event definition:

1. Creation: Create or CreateWithContext establishes a new named event and optional schema.
2. Retrieval: Get or GetWithContext fetches a definition using an ID or name.
3. Listing: ListWithOptions retrieves paginated event definitions.
4. Update: Update modifies the schema of an existing event.
5. Removal: Remove deletes the event definition.

Sources: events.go:72-190

Triggering Events

Triggering an event involves sending a SendEventRequest. This request identifies the event by name and provides the recipient's details (either a ContactId or Email) along with a Payload map.

The sequence shows the synchronous request from the SDK to the API, which returns an acceptance status once the event is queued for processing.
Sources: events.go:193-207, events_test.go:167-184, errors.go:138

Payload Example

When sending an event, the Payload must match the defined schema types.

// Example of sending an event by email address
sent, err := client.Events.SendWithContext(ctx, &resend.SendEventRequest{
    Event: "user.created",
    Email: "user@example.com",
    Payload: map[string]any{
        "plan":     "pro",
        "verified": true,
    },
})

Sources: examples/events.go:94-105

Integration with Automations

Events are primary triggers for Resend Automations. An automation step can be configured with a type AutomationStepTypeTrigger and a configuration mapping to a specific event_name.

This diagram represents the logical link between the SendEventRequest and the AutomationStep configuration.
Sources: events.go:42-47, examples/automations.go:37-46

Error Handling

The service returns specific errors if request construction fails. These are defined as sentinel errors in the resend package.

Error Variable	Description
ErrFailedToCreateEventCreateRequest	Failed to initialize the create request.
ErrFailedToCreateEventGetRequest	Failed to initialize the retrieval request.
ErrFailedToCreateEventListRequest	Failed to initialize the listing request.
ErrFailedToCreateEventUpdateRequest	Failed to initialize the update request.
ErrFailedToCreateEventRemoveRequest	Failed to initialize the deletion request.
ErrFailedToCreateEventSendRequest	Failed to initialize the send/trigger request.

Sources: errors.go:133-140

Conclusion

The Events API provides a structured way to define and signal custom application activities to Resend. By combining schema validation with automation triggers, it enables developers to create reactive email workflows based on specific user actions or system states.