Sending Emails

Relevant source files

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

• resend/emails/_emails.py
• examples/send_email_with_template.py
• tests/emails_test.py
• tests/batch_emails_test.py
• examples/with_headers.py
• examples/templates.py

The email sending module provides a structured interface for dispatching transactional and marketing emails via the Resend API. It supports individual email delivery, batch operations, and template-based messaging with support for both synchronous and asynchronous execution.

The module manages the lifecycle of an email from initial request to delivery tracking. You can define content using HTML or plain text, attach files, and apply custom MIME headers for advanced mail client behavior.

Core Email Sending Process

The resend.Emails.send() method serves as the primary entry point for dispatching a single email. It accepts a SendParams object containing recipient details, content, and optional metadata.

Data Flow for Single Email Sending

The following diagram illustrates the sequence of events when calling the send method.

Send Parameters

The SendParams class defines the structure for an email request.

Parameter	Type	Description
from	str	The sender's email address.
to	str | List[str]	Primary recipient(s).
subject	str	The email subject line.
html	str	The HTML body of the email.
text	str	The plain text body of the email.
attachments	List[Attachment]	Files to include in the email.
headers	Dict[str, str]	Custom MIME headers (e.g., X-Entity-Ref-ID).
scheduled_at	str	ISO 8601 timestamp for delayed sending.
template	EmailTemplate	Reference to a pre-defined template ID and variables.

Sources: resend/emails/_emails.py:206-258, examples/with_headers.py:22-29

Batch Sending

The resend.Batch.send() method allows sending multiple emails in a single API call. This improves efficiency and reduces network overhead for high-volume dispatch.

Batch Validation Modes

When sending batches, you can specify validation behavior via Batch.SendOptions.

• Strict Mode: The operation fails if any email in the batch contains validation errors.
• Permissive Mode: The API processes valid emails and returns a list of specific errors for the invalid ones.

Template-Based Sending

Resend supports dynamic email generation using templates. You create templates with placeholders and then pass the template parameter during the send operation to populate those placeholders.

1. Template Creation: Define HTML content with {{{VARIABLE_NAME}}} syntax.
2. Publishing: Templates must be published before use in the send API.
3. Sending: Pass a EmailTemplate dictionary containing the id and a variables map.

email_template: resend.EmailTemplate = {
    "id": "template-uuid",
    "variables": {
        "NAME": "John Doe",
        "AGE": 30,
    },
}

send_params: resend.Emails.SendParams = {
    "from": "onboarding@resend.dev",
    "to": ["delivered@resend.dev"],
    "template": email_template,
}
resend.Emails.send(send_params)

Sources: examples/send_email_with_template.py:53-68, resend/emails/_emails.py:44-59

Scheduling and Management

Emails can be scheduled for future delivery or canceled if they have not yet been sent.

Scheduling

To delay delivery, provide an ISO 8601 formatted string to the scheduled_at parameter in SendParams. The SDK also allows updating the schedule of an existing email via Emails.update().
Sources: resend/emails/_emails.py:62-72, tests/emails_test.py:72-84

Cancellation

If an email is scheduled, you can stop it from being sent by calling Emails.cancel(email_id). This method returns the ID of the canceled email and its object type.
Sources: resend/emails/_emails.py:85-93, tests/emails_test.py:86-94

Email Metrics and Tracking

The SDK provides access to delivery metrics through the Emails.metrics() endpoint. Metrics can be aggregated by various dimensions.

Metric Dimensions

• period: Aggregation by time buckets (hourly, daily, weekly, monthly).
• domain: Aggregation by sending domain.
• email: Aggregation by specific email ID.
• broadcast: Aggregation by broadcast campaign ID.

Note: The email and broadcast dimensions are mutually exclusive and cannot be combined in a single request.
Sources: resend/emails/_emails.py:270-285, tests/emails_test.py:348-372

Error Handling

The SDK raises specific exceptions based on API responses:

• NoContentError: Raised when the API returns an empty response for a request that expects content.
• ValidationError: Raised when parameter requirements (like expires_in limits) are not met.
• ResendError: General exception for API errors like 404 Not Found.

Sources: tests/emails_test.py:34-42, tests/emails_test.py:141-155

The email sending system integrates tightly with the template and batch systems to provide a flexible environment for outbound communications, ensuring that both simple messages and complex, data-driven campaigns can be managed efficiently.