Sending Single Emails
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/services/emails/model/CreateEmailOptions.java
- src/test/java/com/resend/services/emails/EmailsTest.java
- src/main/java/com/resend/core/net/impl/HttpClient.java
- src/test/java/com/resend/services/util/EmailsUtil.java
- README.md
- src/main/java/com/resend/services/automations/model/SendEmailStepBuilder.java
The resend-java library enables the delivery of individual email messages through a structured API client. You configure email parameters using a builder pattern and dispatch them via the Emails service.
This module handles transactional and marketing communications by interfacing with the Resend /emails endpoint. It supports various content types including plain text, HTML, and predefined templates.
Email Configuration
The CreateEmailOptions class defines the structure of an email request. You use its internal Builder to set recipients, content, and metadata.
Data Model Structure
The following table summarizes the primary fields available when configuring a single email.
| Field | Type | Description |
|---|---|---|
from | String | The sender email address. |
to | List<String> | Primary recipient email addresses. |
subject | String | The email subject line. |
text | String | Plain text version of the message. |
html | String | HTML version of the message. |
cc | List<String> | Carbon copy recipients. |
bcc | List<String> | Blind carbon copy recipients. |
reply_to | List<String> | Reply-to email addresses. |
scheduled_at | String | ISO 8601 timestamp for scheduled delivery. |
template | Template | Template ID and variable configuration. |
Sources: src/main/java/com/resend/services/emails/model/CreateEmailOptions.java:13-53
Recipient and Header Management
The builder provides methods to add individual recipients or lists of recipients for to, cc, and bcc fields. It also supports custom HTTP headers through a map of key-value pairs.
CreateEmailOptions options = CreateEmailOptions.builder()
.from("sender@example.com")
.to("recipient1@example.com", "recipient2@example.com")
.addCc("manager@example.com")
.addHeader("X-Entity-Ref-ID", "12345")
.build();
Sources: src/main/java/com/resend/services/emails/model/CreateEmailOptions.java:125-225, src/test/java/com/resend/services/emails/CreateEmailOptionsTest.java:23-30
Content and Templates
You can provide email content directly or reference a pre-created template. If you provide a template, you cannot include html or text in the same payload.
Template Integration
When using templates, the template object includes the template ID and a map of variables. The SDK merges these variables into the template content on the server side.
The diagram shows the decision path between using direct content or a template during email construction.
Sources: src/main/java/com/resend/services/emails/model/CreateEmailOptions.java:310-323, src/main/java/com/resend/services/automations/model/SendEmailStepBuilder.java:35-85
Execution and Transport
The Emails service uses an IHttpClient implementation, typically backed by OkHttp, to perform the network request.
API Interaction Flow
The SDK transforms the CreateEmailOptions object into a JSON payload. It then executes a POST request to the /emails endpoint.
The sequence diagram illustrates the communication flow from the application through the SDK to the Resend API.
Sources: src/main/java/com/resend/core/net/impl/HttpClient.java:94-110, src/test/java/com/resend/services/emails/EmailsTest.java:108-117
Idempotency
You can include an idempotency key via RequestOptions. This prevents the API from processing the same email request multiple times if a network error occurs.
Sources: src/main/java/com/resend/core/net/impl/HttpClient.java:141-149, src/test/java/com/resend/services/util/EmailsUtil.java:84-87
Error Handling
The SDK validates specific conditions before transmission. For instance, the Builder ensures that lists are initialized before adding items. If the API returns a non-successful status code (e.g., 422 for validation errors), the SDK throws a ResendException.
| Status Code | Description |
|---|---|
| 200 | Success. Returns the email ID. |
| 422 | Validation Error. Invalid recipients or parameters. |
| 404 | Not Found. Resource missing. |
Sources: src/test/java/com/resend/services/emails/EmailsTest.java:120-128, src/main/java/com/resend/core/net/impl/HttpClient.java:236-240
Conclusion
Sending single emails is managed through the Emails service using the CreateEmailOptions builder. The system ensures flexible content management by supporting both direct HTML/text input and dynamic templates. By utilizing idempotency keys and structured HTTP transport, the SDK provides a reliable interface for transactional email delivery.