Skip to main content
Custom Template variables provide your team flexibility when sending emails. Define custom variables for your Template with optional fallback values which will be replaced with the actual values when sending the email.

​
Create custom variables

Each Template may contain up to 20 variables. To add a custom variable, select Variable in the commands palette or type {{ in the editor. Define the name, type, and fallback_value (optional). variable dropdown

You can also define custom variables via the API. The payload can optionally include variables to be used in the Template.

import { Resend } from 'resend';

const resend = new Resend('re_xxxxxxxxx');

await resend.templates.create({
  name: 'order-confirmation',
  html: '<p>Name: {{{PRODUCT}}}</p><p>Total: {{{PRICE}}}</p>',
  variables: [
    {
      key: 'PRODUCT',
      type: 'string',
      fallbackValue: 'item',
    },
    {
      key: 'PRICE',
      type: 'number',
      fallbackValue: 25,
    },
  ],
});
The following variable names are reserved and cannot be used: FIRST_NAME, LAST_NAME, EMAIL, UNSUBSCRIBE_URL, contact,this.
Each variable is an object with the following properties:
  • key: The key of the variable. We recommend capitalizing the key. (e.g. PRODUCT_NAME).
  • type: The type of the variable ('string' or 'number').
  • fallback_value: The fallback value of the variable. If no fallback value is provided, you must provide a value for the variable when sending an email using the template.
See the API reference for more details.

​
Fallback values

When you define a variable, you can optionally define a fallback value. This value will be used when sending the email if you fail to provide a value in your call. In the editor, if you fail to provide a fallback value, a warning sign will show for the variable, which you can remove by providing a value. As shown above, you can also include fallback values when creating a Template via the API.

​
Send Test Emails

You can send test emails to your inbox to preview your Template before sending it to your audience. Provide variable values to test the rendered Template in your inbox.

​
Send a Template with Variables

When sending a transactional email, you can reference your Template and include your variables in the call. The Template variables will be replaced with the actual values.
  • id: id of the published template
  • variables: array of variable objects (if applicable)
Both the /emails and /emails/batch endpoints support Templates. 
import { Resend } from 'resend';

const resend = new Resend('re_xxxxxxxxx');

const { data, error } = await resend.emails.send({
  from: 'Acme <onboarding@resend.dev>',
  to: ['delivered@resend.dev'],
  subject: 'hello world',
  template: {
    id: 'f3b9756c-f4f4-44da-bc00-9f7903c8a83f',
    variables: {
      PRODUCT: 'Laptop',
    },
  },
});
If a template is provided, you cannot send html, text, or react in the payload, otherwise the API will return a validation error.When sending a template, the payload for from, subject, and reply_to take precedence over the template’s defaults for these fields. If the template does not provide a default value for these fields, you must provide them in the payload.
Learn more about sending emails or sending batch emails with Templates via the API.