Introduction & Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Resend Go SDK provides a structured interface for interacting with the Resend API to manage email communications, contact lifecycles, and automated workflows. Version 3.0.0 introduced significant architectural changes, moving toward struct-based arguments for enhanced ergonomics and expanding support for sophisticated features like Topics, Segments, and multi-step Automations.
Sources: CHANGELOG.md:3-15
Core Service Architecture
The SDK organizes functionality into specialized services accessible through a central Client. Each service handles a distinct domain of the Resend ecosystem.
Service Modules
- Emails: Handles sending basic emails, templated emails, and listing historical records.
- Contacts: Manages global and audience-specific contacts, including their properties and segment memberships.
- Templates: Allows creation, publication, and duplication of reusable email content with dynamic variables.
- Topics: Manages subscription preferences for granular communication control.
- Automations: Orchestrates multi-step workflows triggered by specific events.
- Webhooks: Configures endpoints for receiving real-time event notifications from the API.
Sources: CHANGELOG.md:16-30, examples/automations.go:17-25, examples/webhooks.go:17-25
Request Flow
The following diagram illustrates the typical interaction between the SDK client and the Resend API.
The SDK uses a standard pattern where service methods accept a context.Context and a request struct, returning a response struct and an error.
Sources: topics.go:68-100, examples/send_email.go:17-36
Key Data Structures
Pagination Options
Many listing operations across the SDK utilize a common ListOptions structure to manage large datasets through cursor-based pagination.
| Field | Type | Description |
|---|---|---|
Limit | *int | Maximum number of records to return (default 20). |
After | *string | Cursor for fetching the next page of results. |
Before | *string | Cursor for fetching the previous page of results. |
Sources: examples/topics.go:73-77, examples/send_email.go:78-85
Topic Subscription Models
Topics allow users to segment communications based on recipient preferences. A topic defines a default subscription behavior that applies when a contact's preference is not explicitly set.
Sources: topics.go:9-14, examples/send_email.go:111-115
Component Interactions
The SDK allows for complex interactions between different modules, such as using Templates within Automations or assigning Contacts to Segments and Topics simultaneously.
Workflow Example: Automation with Templates
Automations utilize Templates as steps in a workflow. A trigger event (e.g., user.created) initiates the flow, which can include delays and conditional steps.
Sources: examples/automations.go:145-190
Global Contact Management
Version 3.0.0 shifted the Contact API to support global contacts, where AudienceId is optional. This allows contacts to exist project-wide and carry custom properties.
| Feature | Description | File Reference |
|---|---|---|
| Properties | Custom key-value pairs assigned to contacts. | examples/global_contacts.go:42-53 |
| Segments | Groupings of contacts for targeted broadcasts (replaces Audiences). | CHANGELOG.md:23-25 |
| Import | Bulk creation of contacts from CSV files with column mapping. | examples/contact_imports.go:19-45 |
Summary
The Resend Go SDK provides a type-safe, service-oriented wrapper around the Resend API. By utilizing struct-based configurations and standardized pagination, it enables developers to integrate email sending, contact management, and complex automations into Go applications. The modular design ensures that updates to specific features, like the Contacts or Templates services, do not negatively impact the core email-sending functionality.
Sources: CHANGELOG.md:5-10, topics.go:53-65