Serialization & Data Converters
Relevant source files
The following files were used as context for generating this wiki page:
Serialization and data converters handle the translation between .NET types and the JSON formats required by the Resend API. These components ensure that complex types, such as polymorphic webhook events and flexible date-time strings, are correctly processed during HTTP communication.
The system uses System.Text.Json as the primary serialization engine. Custom converters address specific API requirements, such as partial updates where explicit nulls signal field clearing, and the support for "human-readable" relative time strings.
Sources: src/Resend/Json/InboxDraftUpdateDataConverter.cs, src/Resend/Json/DateTimeOrHumanConverter.cs
Polymorphic Webhook Conversion
The WebhookEventConverter manages the deserialization of incoming webhook payloads. It identifies the specific event type from the JSON type property and maps it to the corresponding data model.
Event Processing Flow
The converter reads the top-level properties of the webhook payload to determine the structure of the data object.
The converter ensures that the type, created_at, and data properties are present before proceeding with object creation.
Sources: src/Resend.Webhooks/Json/WebhookEventConverter.cs:25-88
Partial Update Serialization
Certain API endpoints distinguish between a missing property and a property explicitly set to null. The SDK uses specialized converters to handle these "patch" operations.
Inbox Update Converters
InboxDraftUpdateDataConverter and InboxAgentUpdateDataConverter track which properties have been assigned values. They only write properties to the JSON output if they were explicitly modified in the code.
| Converter | Target Class | Key Behavior |
|---|---|---|
InboxDraftUpdateDataConverter | InboxDraftUpdateData | Writes to, cc, bcc, subject, html, text, and attachments only if assigned. |
InboxAgentUpdateDataConverter | InboxAgentUpdateData | Writes instructions, tone, and actions only if assigned. |
Sources: src/Resend/Json/InboxDraftUpdateDataConverter.cs:11-13, src/Resend/Json/InboxAgentUpdateDataConverter.cs:10-12
Assignment Validation Logic
The converters use a WriteAssigned helper method to verify property status before writing to the Utf8JsonWriter.
private static void WriteAssigned<T>( Utf8JsonWriter writer, InboxDraftUpdateData value, string propertyName, T propertyValue, JsonSerializerOptions options )
{
if ( value.IsAssigned( propertyName ) == false )
return;
writer.WritePropertyName( propertyName );
JsonSerializer.Serialize( writer, propertyValue, options );
}
Sources: src/Resend/Json/InboxDraftUpdateDataConverter.cs:91-98
Specialized Value Converters
The SDK includes several converters for specific data formats used across the API.
Date and Time Handling
DateTimeOrHumanConverter supports fields that can accept either a standard ISO 8601 timestamp or a relative human-readable string (e.g., "in 5 minutes").
- Read: Detects if the token is a string and attempts to parse it as a
DateTime. If parsing fails or the format is relative, it stores the raw string. - Write: Outputs the
DateTimevalue if present; otherwise, it writes the stored human-readable string.
Sources: src/Resend/Json/DateTimeOrHumanConverter.cs:11-66
Data Type Converters
| Converter | Description |
|---|---|
ByteArrayOrStringConverter | Converts between JSON strings and .NET byte[] arrays. |
JsonStringEnumValueConverter<T> | Maps enum members to specific string values defined by API attributes. |
JsonUtcDateTimeConverter | Ensures all DateTime objects are treated as UTC during serialization. |
Sources: src/Resend/Json/ByteArrayOrStringConverter.cs, src/Resend/Json/JsonStringEnumValueConverter.cs, src/Resend.Webhooks/Json/WebhookEventConverter.cs:12-13
Summary
The serialization layer provides the necessary logic to handle the Resend API's dynamic and polymorphic data structures. By using custom JsonConverter implementations, the SDK maintains strict .NET typing while supporting the flexible requirements of webhooks and partial resource updates.