unsent
unsent.dev
API Reference

Templates

The Templates API allows you to manage reusable email templates.

Base URL

https://api.unsent.dev/v1/templates

Features

Reusable Content

Create templates with HTML and Text content

Easy Creation

Design and save email layouts

Updates

Modify existing templates easily

Overview

The Templates API allows you to create, manage, and reuse email templates. Templates define the subject, HTML content, and text content for emails, enabling consistent branding and reducing repetitive work. Templates can be used with the Send Email endpoint by specifying a templateId.

Quick Start

List Templates

Retrieve all email templates for your team.

curl -X GET https://api.unsent.dev/v1/templates \
  -H "Authorization: Bearer your-api-key"

Example Response:

[
  {
    "id": "tmpl_abc123",
    "name": "Welcome Email",
    "subject": "Welcome to Our Service!",
    "html": "<html><body><h1>Welcome {{name}}!</h1></body></html>",
    "content": "Welcome {{name}}!",
    "teamId": "team_xyz789",
    "createdAt": "2026-01-05T10:00:00.000Z",
    "updatedAt": "2026-01-05T10:00:00.000Z"
  },
  {
    "id": "tmpl_def456",
    "name": "Newsletter",
    "subject": "This Week's Updates",
    "html": "<html><body><h2>News</h2><p>{{content}}</p></body></html>",
    "content": null,
    "teamId": "team_xyz789",
    "createdAt": "2026-01-04T15:30:00.000Z",
    "updatedAt": "2026-01-05T09:20:00.000Z"
  }
]

[!NOTE] Templates are returned in descending order by creation date (newest first).

Create a Template

Create a new email template with reusable content.

curl -X POST https://api.unsent.dev/v1/templates \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Email",
    "subject": "Welcome to our service!",
    "html": "<html><body><h1>Welcome {{name}}!</h1><p>We are excited to have you.</p></body></html>",
    "content": "Welcome {{name}}! We are excited to have you."
  }'

Request Body

FieldTypeRequiredDescription
namestringYesTemplate name for identification (min: 1 character)
subjectstringYesEmail subject line (Required)
htmlstringNoHTML version of the email content
contentstringNoPlain text version of the email content

Example Response:

{
  "id": "tmpl_new123"
}

[!TIP] Use variables like {{name}} or {{company}} in your templates. These can be replaced with actual values when sending emails.

Get a Template

Retrieve details of a specific template by ID.

curl -X GET https://api.unsent.dev/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer your-api-key"

Example Response:

{
  "id": "tmpl_abc123",
  "name": "Welcome Email",
  "subject": "Welcome to Our Service!",
  "html": "<html><body><h1>Welcome {{name}}!</h1></body></html>",
  "content": "Welcome {{name}}!",
  "teamId": "team_xyz789",
  "createdAt": "2026-01-05T10:00:00.000Z",
  "updatedAt": "2026-01-05T10:00:00.000Z"
}

Error Response (404):

{
  "code": "NOT_FOUND",
  "message": "Template not found"
}

Update a Template

Update an existing template. All fields are optional—only include the fields you want to change.

curl -X PATCH https://api.unsent.dev/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Welcome to Our Amazing Service!",
    "html": "<html><body><h1>Welcome {{name}}!</h1><p>Updated content here.</p></body></html>"
  }'

Request Body

FieldTypeRequiredDescription
namestringNoUpdated template name
subjectstringNoUpdated email subject
htmlstringNoUpdated HTML content
contentstringNoUpdated text content

Example Response:

{
  "success": true
}

Delete a Template

Permanently delete a template.

curl -X DELETE https://api.unsent.dev/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer your-api-key"

Example Response:

{
  "success": true
}

[!WARNING] Deleting a template is permanent and cannot be undone. Make sure you no longer need this template before deleting.

Response Schema

Template Object

FieldTypeDescription
idstringUnique template identifier
namestringTemplate name
subjectstringEmail subject line
htmlstring | nullHTML email content (optional)
contentstring | nullPlain text email content (optional)
teamIdstringYour team identifier
createdAtstringISO 8601 timestamp of creation
updatedAtstringISO 8601 timestamp of last update

Using Templates with Emails

To send an email using a template, specify the templateId when calling the Send Email endpoint:

curl -X POST https://api.unsent.dev/v1/emails \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "templateId": "tmpl_abc123"
  }'

[!NOTE] When using templateId, the template's subject, html, and content are used automatically. You can override these by explicitly providing them in the request.

Best Practices

Organize Templates

Use clear, descriptive names like "Welcome-New-User" or "Invoice-Reminder"

Test Before Use

Send test emails with your templates before using them in campaigns

Version Control

Keep track of template changes by updating them regularly

API Endpoints

Teams

The Teams API allows you to manage team information and retrieve details about the current workspace.

Webhooks

The Webhooks API allows you to receive real-time notifications when events occur in your Unsent account.

On this page

Base URLFeaturesOverviewQuick StartList TemplatesCreate a TemplateRequest BodyGet a TemplateUpdate a TemplateRequest BodyDelete a TemplateResponse SchemaTemplate ObjectUsing Templates with EmailsBest PracticesAPI Endpoints