Initial push of Plunk Next
This commit is contained in:
Dries Augustyns
@@ -0,0 +1,256 @@
|
||||
---
|
||||
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": "[email protected]",
|
||||
"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": "[email protected]",
|
||||
"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": "[email protected]",
|
||||
"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": "[email protected]",
|
||||
"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": "[email protected]",
|
||||
"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
|
||||
Reference in New Issue
Block a user