plunk/apps/wiki/content/docs/guides/templates.mdx

---
title: Templates
description: Create reusable email templates
---

## Why use templates

Templates let you design emails once and reuse them across:
- Transactional API sends (`/v1/send`)
- Automated workflows

Benefits:
- Update design in one place, applies everywhere
- Maintain consistent branding
- Separate content from code

## Template types

### Marketing templates

**Use for:** Newsletters, promotions, announcements

- Only sends to subscribed contacts
- Automatically includes unsubscribe link
- Respects subscription preferences

### Transactional templates

**Use for:** Order confirmations, password resets, receipts

- Sends to all contacts, even if unsubscribed
- No unsubscribe link required
- Critical business communications

Choose the right type based on content, not delivery method. You can use both types in campaigns, workflows, and API calls. The type determines subscription enforcement.

## Creating templates

### In the dashboard

1. Go to **Templates**
2. Click **Create Template**
3. Choose type (Marketing or Transactional)
4. Set subject, from address, and body
5. Add variables using `{{variableName}}`
6. Save

### Via API

```bash
curl -X POST {{API_URL}}/templates \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order-confirmation",
    "subject": "Order #{{orderNumber}} confirmed",
    "body": "<h1>Thanks for your order!</h1><p>Order #{{orderNumber}} will arrive by {{deliveryDate}}.</p>",
    "from": "orders@example.com",
    "fromName": "Acme Store",
    "type": "TRANSACTIONAL"
  }'
```

## Using variables

Variables let you personalize each email. Use `{{variableName}}` syntax:

```html
<h1>Hello {{firstName}}!</h1>
<p>Your {{plan}} subscription renews on {{renewalDate}}.</p>
<p>Total: ${{amount}}</p>
```

When sending, provide values in the `data` object:

```json
{
  "template": "subscription-renewal",
  "data": {
    "firstName": "Sarah",
    "plan": "Pro",
    "renewalDate": "April 15, 2024",
    "amount": "29.00"
  }
}
```

## Persistent vs. Temporary Data

Template variables can come from **persistent contact data** or **temporary non-persistent data**:

**Persistent data** — Saved to contact profile:
```json
{
  "to": "user@example.com",
  "subject": "Welcome {{firstName}}!",
  "body": "<p>Your {{plan}} subscription is active.</p>",
  "data": {
    "firstName": "John",  // Saved to contact
    "plan": "Pro"         // Saved to contact
  }
}
```

**Non-persistent data** — Used only for this email:
```json
{
  "to": "user@example.com",
  "subject": "Password Reset",
  "body": "<p>Reset code: {{resetCode}}</p><p>Hello {{firstName}}!</p>",
  "data": {
    "firstName": "John",                            // Saved to contact
    "resetCode": {value: "ABC123", persistent: false}  // NOT saved to contact
  }
}
```

**When to use non-persistent data:**
- One-time verification codes or tokens
- Temporary URLs (password reset, magic links)
- Session-specific information
- Data that shouldn't pollute contact profiles

**In workflows:**
Non-persistent data from events is available throughout the entire workflow execution via the execution context, allowing you to use tokens/URLs across multiple workflow steps.

### Fallback values

Provide defaults for missing data:

```html
<h1>Hello {{firstName ?? 'there'}}!</h1>
```

If `firstName` isn't provided, displays "Hello there!" instead.

### Nested data

Access nested objects with dot notation:

```html
<p>{{user.email}}</p>
<p>{{order.items.0.name}}</p>
<p>{{preferences.newsletter}}</p>
```

## Sending with templates

### Transactional emails

```bash
curl -X POST {{API_URL}}/v1/send \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "template": "order-confirmation",
    "data": {
      "orderNumber": "12345",
      "deliveryDate": "March 20"
    }
  }'
```

### In workflows

When creating a **Send Email** workflow step, select the template from the dropdown. Variables are automatically filled from contact data and workflow context.

### In campaigns

When creating a campaign, choose a template instead of composing inline. All campaign recipients get the same template with personalized variables.

## When to use inline vs templates

**Use templates when:**
- Sending the same email repeatedly
- Multiple workflows/campaigns use same design
- Design may change over time
- Want to centralize branding

**Use inline content when:**
- One-off transactional emails
- Unique per-user content
- Testing or prototyping
- Content is generated dynamically

Example inline send:

```bash
curl -X POST {{API_URL}}/v1/send \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Your verification code",
    "body": "<p>Your code: {{code}}</p>",
    "data": {"code": "ABC123"}
  }'
```

## Managing templates

### List templates

```bash
curl -X GET {{API_URL}}/templates \
  -H "Authorization: Bearer sk_your_secret_key"
```

Filter by type:

```bash
curl -X GET "{{API_URL}}/templates?type=MARKETING" \
  -H "Authorization: Bearer sk_your_secret_key"
```

### Update template

```bash
curl -X PATCH {{API_URL}}/templates/template_id \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "New subject line",
    "body": "<p>Updated content</p>"
  }'
```

Changes apply to all future sends using this template.

### Delete template

```bash
curl -X DELETE {{API_URL}}/templates/template_id \
  -H "Authorization: Bearer sk_your_secret_key"
```

Templates used in active workflows are not deleted—you'll need to update workflows first.

## Best practices

**Keep templates simple** — Focus on content, avoid complex layouts that break in email clients.

**Test across clients** — Email rendering varies. Preview in Gmail, Outlook, Apple Mail, and mobile devices.

**Use semantic HTML** — Use `<h1>`, `<p>`, `<strong>` instead of styled `<div>` elements.

**Provide all variables** — Missing variables display as empty. Use fallbacks: `{{name ?? 'Customer'}}`.

**Version your templates** — For critical transactional emails, create new templates rather than editing existing ones.

## Next Steps

- [Create campaigns](/guides/campaigns) with your templates
- [Build workflows](/guides/workflows) with automated emails
- [Track performance](/guides/analytics) of your templates