Templates Management

Relevant source files

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

• resend/templates/_templates.py
• resend/templates/_template.py
• resend/emails/_emails.py
• examples/templates.py
• examples/send_email_with_template.py
• tests/templates_test.py
• tests/templates_async_test.py

Templates Management allows you to create, manage, and publish email templates with dynamic variables. The Templates API provides synchronous and asynchronous methods to handle the lifecycle of a template from creation to deletion. Templates serve as blueprints for emails, supporting both HTML and plain text versions with variable interpolation using triple braces (e.g., {{{NAME}}}).

You must publish a template before using it to send emails. Once published, you can reference the template by its unique ID in the Email API and provide specific values for the defined variables.

Sources: resend/templates/_templates.py:27-30, examples/templates.py:25-40, examples/send_email_with_template.py:53-65

Template Lifecycle and Operations

The lifecycle of a template involves creation, optional updates or duplication, publication, and eventual removal.

Template Operations Flow

The following diagram illustrates the standard workflow for managing a template:

Sources: examples/templates.py:25-70, resend/templates/_templates.py:228-300

Key API Methods

The Templates class provides the following operations:

Method	Description	Path	Verb
create()	Creates a new template draft.	/templates	POST
get()	Retrieves a specific template by ID.	/templates/{id}	GET
list()	Lists all templates with pagination.	/templates	GET
update()	Updates an existing template.	/templates/{id}	PATCH
publish()	Makes a template available for email sending.	/templates/{id}/publish	POST
duplicate()	Creates a copy of an existing template.	/templates/{id}/duplicate	POST
remove()	Deletes a template from the system.	/templates/{id}	DELETE

Sources: resend/templates/_templates.py:228-316

Data Models and Variables

Templates utilize specific data structures for configuration and variable management. Each template can contain up to 20 variables.

Variable Structure

A Variable defines a placeholder within the template content.

Field	Type	Description
key	str	The variable name used in the template (e.g., "NAME").
type	str	The data type, such as "string" or "number".
fallback_value	Union[str, int]	The default value used if no variable value is provided during sending.

Sources: examples/templates.py:11-23, resend/templates/_templates.py:61-62

Template Parameters

The CreateParams class defines the requirements for establishing a new template.

class CreateParams(_CreateParamsFrom):
    name: str # Required template name
    html: str # Required HTML content
    alias: NotRequired[str]
    subject: NotRequired[str]
    variables: NotRequired[List[Variable]] # Up to 20 variables

Sources: resend/templates/_templates.py:32-62

Integration with Emails

To send an email using a template, you must provide an EmailTemplate object within the SendParams. This object includes the id of a published template and a dictionary mapping variable keys to their values.

Email Sending Sequence

Code Example: Sending with Variables

# Configuration for the email send operation
email_template: resend.EmailTemplate = {
    "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794",
    "variables": {
        "NAME": "John Doe",
        "AGE": 30,
    },
}

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

email = resend.Emails.send(send_params)

Sources: examples/send_email_with_template.py:53-68, resend/emails/_emails.py:84-98

Asynchronous Support

The module includes _async versions for all primary operations, allowing for non-blocking I/O. These methods utilize AsyncRequest to perform API calls.

• create_async(params)
• get_async(template_id)
• list_async(params)
• update_async(params)
• publish_async(template_id)
• duplicate_async(template_id)
• remove_async(template_id)

Sources: resend/templates/_templates.py:318-403, tests/templates_async_test.py:15-120

Summary

Templates Management provides a structured way to handle dynamic email content. By separating template definitions from delivery logic, users can manage complex layouts and dynamic data through a centralized API. The system ensures safety by requiring a publication step before usage and enforces constraints like a 20-variable limit per template.

Sources: resend/templates/_templates.py:27-30, examples/templates.py:1-73