Data Serialization and Mapping
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/core/mapper/IMapper.java
- src/main/java/com/resend/core/mapper/ResendMapper.java
- src/main/java/com/resend/services/contacts/model/CreateContactImportOptions.java
- src/main/java/com/resend/services/contacts/model/ContactImportColumnMap.java
- src/main/java/com/resend/services/templates/Templates.java
- src/main/java/com/resend/services/contacts/ContactImports.java
- src/main/java/com/resend/services/topics/model/AbstractTopic.java
- src/main/java/com/resend/services/events/model/EventSummary.java
Data Serialization and Mapping in the Resend Java SDK handles the conversion between Java objects and their JSON representations for API communication. The system ensures that request payloads are correctly formatted for the Resend API and that API responses are accurately transformed back into strongly-typed Java entities.
Architecture and Components
The mapping architecture relies on a central abstraction layer to decouple the SDK services from specific JSON processing implementations.
Core Mapping Interfaces
The IMapper interface defines the contract for serialization and deserialization. It provides two primary operations: writeValue for converting objects to JSON strings and readValue for converting JSON strings into specific Java classes.
Sources: src/main/java/com/resend/core/mapper/IMapper.java:6-26
ResendMapper Implementation
ResendMapper implements IMapper using the Jackson ObjectMapper library. It configures the mapper with specific behaviors:
- Non-null Inclusion: Only serializes fields that are not null.
- Graceful Deserialization: Ignores unknown properties in the JSON response to prevent errors when the API introduces new fields.
Sources: src/main/java/com/resend/core/mapper/ResendMapper.java:11-53
The following diagram illustrates the relationship between the mapping components and the services:
Data Flow
Data flows through the mapper during both request preparation and response handling.
Request Serialization
When a service method like Templates.create or ContactImports.create is called, the service uses the internal resendMapper to convert the options object into a JSON payload string before sending the HTTP request.
Sources: src/main/java/com/resend/services/templates/Templates.java:43, src/main/java/com/resend/services/contacts/ContactImports.java:76
Response Deserialization
Upon receiving a successful HTTP response, the SDK converts the JSON body back into Java objects. Standard service methods use the execute helper, which internally invokes readValue to produce the expected response type.
Sources: src/main/java/com/resend/services/templates/Templates.java:54, src/main/java/com/resend/core/mapper/ResendMapper.java:45-53
Specialized Mapping Logic
Certain modules require custom handling beyond standard JSON serialization.
Multipart and Contact Imports
The ContactImports service handles CSV files using multipart/form-data. While the file is sent as a raw stream or byte array, secondary metadata like column_map, segments, and topics are manually serialized to JSON strings using the mapper before being added as form fields.
Sources: src/main/java/com/resend/services/contacts/ContactImports.java:75-85
Annotation-Driven Mapping
The SDK uses Jackson annotations to manage field naming discrepancies between Java conventions (camelCase) and API conventions (snake_case).
| Java Class | Field Name | JSON Property |
|---|---|---|
AbstractTopic | defaultSubscription | default_subscription |
AbstractTopic | createdAt | created_at |
ContactImportColumnMap | firstName | first_name |
EventSummary | createdAt | created_at |
Sources: src/main/java/com/resend/services/topics/model/AbstractTopic.java:31-43, src/main/java/com/resend/services/contacts/model/ContactImportColumnMap.java:23, src/main/java/com/resend/services/events/model/EventSummary.java:21
Constraints and Configuration
The serialization behavior is governed by several configurations within ResendMapper:
| Configuration | Type | Description |
|---|---|---|
JsonInclude.Include.NON_NULL | Inclusion Policy | Prevents null fields from appearing in the output JSON. |
FAIL_ON_UNKNOWN_PROPERTIES | Deserialization Feature | Set to false to ensure compatibility with API updates. |
MAX_FILE_SIZE_BYTES | Constant | Limits contact import files to 50MB (52,428,800 bytes). |
Sources: src/main/java/com/resend/core/mapper/ResendMapper.java:18-20, src/main/java/com/resend/services/contacts/model/CreateContactImportOptions.java:27
Example: Manual Serialization in Contact Imports
// Logic within ContactImports.java
if (options.getColumnMap() != null) {
formFields.put("column_map", super.resendMapper.writeValue(options.getColumnMap()));
}
Sources: src/main/java/com/resend/services/contacts/ContactImports.java:75-77
Summary
The Data Serialization and Mapping module provides a robust mechanism for translating Java domain models into Resend API payloads. By utilizing the IMapper interface and Jackson-powered ResendMapper, the SDK maintains flexible deserialization that ignores unknown properties and efficient serialization that omits null values. This structure supports both standard RESTful JSON interactions and complex multipart imports.