List Templates

Retrieve a list of all published templates in your Emailit account. Only templates with published_at set are returned. Content (html/text) is excluded from list view.

GET/templates

Query Parameters

per_pageinteger

Items per page (1-100). Default: 25.

pageinteger

Page number (minimum: 1). Default: 1.

filter[name]string

Filter by name (partial match).

filter[alias]string

Filter by alias (exact match).

filter[editor]string

Filter by editor type: html, tiptap, or dragit.

sortstring

Sort field: name, alias, created_at, updated_at, or published_at. Default: created_at.

orderstring

Sort order: asc or desc. Default: desc.

GET /templates

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const templates = await emailit.templates.list();

from emailit import EmailitClient
client = EmailitClient("your_api_key")

templates = client.templates.list()

$emailit = Emailit::client('your_api_key');

$templates = $emailit->templates()->list();

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

templates = client.templates.list

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

templates, err := client.Templates.List(nil)

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let templates = emailit.templates.list(None).await?;

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject templates = emailit.templates().list();

using Emailit;
var emailit = new EmailitClient("your_api_key");

var templates = emailit.Templates.List();

use Emailit\Laravel\Facades\Emailit;

$templates = Emailit::templates()->list();

curl https://api.emailit.com/v2/templates \
  -H "Authorization: Bearer your_api_key"

{
  "data": [
    {
      "id": "tem_47TaFwzJx6mD7NeJYvLjFxVwbgT",
      "name": "Welcome Email",
      "alias": "welcome-email",
      "from": "Support <support@company.com>",
      "subject": "Welcome to our service!",
      "reply_to": ["support@company.com"],
      "editor": "html",
      "published_at": "2025-12-24T10:30:00.000000Z",
      "preview_url": "https://cdn.company.com/previews/welcome.png",
      "total_versions": 3,
      "created_at": "2025-12-24T09:00:00.000000Z",
      "updated_at": "2025-12-24T10:30:00.000000Z"
    }
  ],
  "total_records": 10,
  "per_page": 25,
  "current_page": 1,
  "total_pages": 1
}

{
  "message": "Unauthorized"
}

Get Template

Retrieve a template by ID with full content and all other versions (templates with the same alias).

GET/templates/:id

Path Parameters

idstringRequired

Template ID (e.g., tem_47TaFwzJx6mD7NeJYvLjFxVwbgT).

GET /templates/{id}

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const template = await emailit.templates.get('tem_123');

from emailit import EmailitClient
client = EmailitClient("your_api_key")

template = client.templates.get("tem_123")

$emailit = Emailit::client('your_api_key');

$template = $emailit->templates()->get('tem_123');

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

template = client.templates.get("tem_123")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

template, err := client.Templates.Get("tem_123")

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let template = emailit.templates.get("tem_123").await?;

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject template = emailit.templates().get("tem_123");

using Emailit;
var emailit = new EmailitClient("your_api_key");

var template = emailit.Templates.Get("tem_123");

use Emailit\Laravel\Facades\Emailit;

$template = Emailit::templates()->get('tem_123');

curl https://api.emailit.com/v2/templates/tem_123 \
  -H "Authorization: Bearer your_api_key"

{
  "data": {
    "id": "tem_47TaFwzJx6mD7NeJYvLjFxVwbgT",
    "name": "Welcome Email v1",
    "alias": "welcome-email",
    "from": "Support <support@company.com>",
    "subject": "Welcome!",
    "reply_to": ["support@company.com"],
    "html": "<h1>Welcome!</h1>",
    "text": "Welcome!",
    "editor": "html",
    "published_at": "2025-12-24T10:30:00.000000Z",
    "preview_url": "https://cdn.company.com/previews/welcome.png",
    "created_at": "2025-12-24T09:00:00.000000Z",
    "updated_at": "2025-12-24T10:30:00.000000Z",
    "versions": [
      {
        "id": "tem_anotherOidHere123456789",
        "name": "Welcome Email v2",
        "published_at": null,
        "created_at": "2025-12-24T11:00:00.000000Z",
        "updated_at": "2025-12-24T11:00:00.000000Z"
      }
    ]
  }
}

{
  "message": "Template not found"
}

Key Concepts

Alias Grouping

Templates with the same alias are versions of the same template. When you fetch a template by ID, the versions array includes all other templates that share the same alias.

Publishing

Only one template per alias can be published at any time. The published template has a non-null published_at timestamp. Draft templates have published_at set to null.

Create Template

Create a new template through the Emailit API. Templates are automatically published if the alias doesn’t exist yet; otherwise, they remain as drafts.

POST/templates

Request Body

namestringRequired

Template name. Maximum 191 characters.

aliasstringRequired

Template alias for grouping versions. Must contain only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-). Pattern: ^[a-z0-9_-]+$. Maximum 191 characters.

fromstring

From email address in RFC format (e.g., Name <email@domain.com>). Maximum 191 characters.

subjectstring

Email subject line. Maximum 191 characters.

reply_tostring | string[]

Single email or array of email addresses for reply-to.

htmlstring

HTML content for the email template.

textstring

Plain text content for the email template.

editorstring

Editor type: html (default), tiptap, or dragit.

POST /templates

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const template = await emailit.templates.create({
  name: 'Welcome',
  subject: 'Welcome!',
  html: '<h1>Hello {{name}}</h1>'
});

from emailit import EmailitClient
client = EmailitClient("your_api_key")

template = client.templates.create({
    "name": "Welcome",
    "subject": "Welcome!",
    "html": "<h1>Hello {{name}}</h1>"
})

$emailit = Emailit::client('your_api_key');

$template = $emailit->templates()->create([
    'name' => 'Welcome',
    'subject' => 'Welcome!',
    'html' => '<h1>Hello {{name}}</h1>'
]);

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

template = client.templates.create(
  name: "Welcome",
  subject: "Welcome!",
  html: "<h1>Hello {{name}}</h1>"
)

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

template, err := client.Templates.Create(&emailit.CreateTemplateRequest{
    Name: "Welcome",
    Subject: "Welcome!",
    Html: "<h1>Hello {{name}}</h1>",
})

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let template = emailit.templates.create(
    emailit::types::CreateTemplateParams::new("Welcome")
        .with_subject("Welcome!")
        .with_html("<h1>Hello {{name}}</h1>")
).await?;

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject template = emailit.templates().create(
    TemplateCreateParams.builder()
        .setName("Welcome")
        .setSubject("Welcome!")
        .setHtml("<h1>Hello {{name}}</h1>")
        .build()
);

using Emailit;
var emailit = new EmailitClient("your_api_key");

var template = emailit.Templates.Create(new TemplateCreateOptions {
    Name = "Welcome",
    Subject = "Welcome!",
    Html = "<h1>Hello {{name}}</h1>"
});

use Emailit\Laravel\Facades\Emailit;

$template = Emailit::templates()->create([
    'name' => 'Welcome',
    'subject' => 'Welcome!',
    'html' => '<h1>Hello {{name}}</h1>'
]);

curl https://api.emailit.com/v2/templates \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome",
    "subject": "Welcome!",
    "html": "<h1>Hello {{name}}</h1>"
  }'

{
  "data": {
    "id": "tem_47TaFwzJx6mD7NeJYvLjFxVwbgT",
    "name": "Welcome Email",
    "alias": "welcome-email",
    "from": "Support <support@company.com>",
    "subject": "Welcome to our service!",
    "reply_to": ["support@company.com"],
    "html": "<h1>Welcome!</h1><p>Thanks for joining us.</p>",
    "text": "Welcome! Thanks for joining us.",
    "editor": "html",
    "published_at": "2025-12-24T10:30:00.000000Z",
    "preview_url": null,
    "created_at": "2025-12-24T10:30:00.000000Z",
    "updated_at": "2025-12-24T10:30:00.000000Z"
  },
  "message": "Template was successfully created."
}

{
  "message": "Validation failed",
  "errors": {
    "name": ["Name is required"],
    "alias": ["Alias must contain only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-)"]
  }
}

Auto-Publishing Behavior

New alias: When you create a template with an alias that doesn’t exist yet, the template is automatically published (published_at is set).
Existing alias: When you create a template with an alias that already has templates, the new template is saved as a draft (published_at is null). You can publish it later using the Publish Template endpoint.

Validation Rules

Field	Rules
`name`	Required, max 191 characters
`alias`	Required, max 191 characters, pattern: `^[a-z0-9_-]+$`
`from`	Optional, max 191 characters
`subject`	Optional, max 191 characters
`reply_to`	Optional, must be valid email(s)
`editor`	Optional, must be `html`, `tiptap`, or `dragit`

Update Template

Update an existing template through the Emailit API. All fields are optional. This endpoint does not change the published_at status.

POST/templates/:id

Path Parameters

idstringRequired

Template ID (e.g., tem_47TaFwzJx6mD7NeJYvLjFxVwbgT).

Request Body (all optional)

namestring

Template name. Maximum 191 characters.

aliasstring

Template alias. Must be unique if changing. Must contain only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-). Maximum 191 characters.

fromstring

From email address in RFC format. Maximum 191 characters.

subjectstring

Email subject line. Maximum 191 characters.

reply_tostring | string[]

Reply-to email address(es).

htmlstring

HTML content for the email template.

textstring

Plain text content for the email template.

editorstring

Editor type: html, tiptap, or dragit.

PATCH /templates/{id}

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const template = await emailit.templates.update('tem_123', {
  subject: 'Updated Subject'
});

from emailit import EmailitClient
client = EmailitClient("your_api_key")

template = client.templates.update("tem_123", {
    "subject": "Updated Subject"
})

$emailit = Emailit::client('your_api_key');

$template = $emailit->templates()->update('tem_123', [
    'subject' => 'Updated Subject'
]);

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

template = client.templates.update("tem_123", subject: "Updated Subject")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

template, err := client.Templates.Update("tem_123", &emailit.UpdateTemplateRequest{
    Subject: "Updated Subject",
})

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let template = emailit.templates.update("tem_123",
    emailit::types::UpdateTemplateParams {
        subject: Some("Updated Subject".into()),
        ..Default::default()
    }
).await?;

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject template = emailit.templates().update("tem_123",
    TemplateUpdateParams.builder()
        .setSubject("Updated Subject")
        .build()
);

using Emailit;
var emailit = new EmailitClient("your_api_key");

var template = emailit.Templates.Update("tem_123", new TemplateUpdateOptions {
    Subject = "Updated Subject"
});

use Emailit\Laravel\Facades\Emailit;

$template = Emailit::templates()->update('tem_123', [
    'subject' => 'Updated Subject'
]);

curl -X PATCH https://api.emailit.com/v2/templates/tem_123 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Updated Subject"}'

{
  "data": {
    "id": "tem_47TaFwzJx6mD7NeJYvLjFxVwbgT",
    "name": "Welcome Email - Updated",
    "alias": "welcome-email",
    "from": "Support <support@company.com>",
    "subject": "Welcome! We are glad you are here",
    "reply_to": ["support@company.com"],
    "html": "<h1>Welcome!</h1>",
    "text": "Welcome!",
    "editor": "html",
    "published_at": "2025-12-24T10:30:00.000000Z",
    "preview_url": null,
    "created_at": "2025-12-24T10:30:00.000000Z",
    "updated_at": "2025-12-24T12:00:00.000000Z"
  },
  "message": "Template was successfully updated."
}

{
  "message": "Validation failed",
  "errors": {
    "alias": ["Alias already exists"]
  }
}

{
  "message": "Template not found"
}

Important Notes

Updating a template does not change its published_at status. A published template remains published, and a draft remains a draft.
If you change the alias to one that already exists, you’ll receive a validation error.
To publish a draft template, use the Publish Template endpoint.

Delete Template

Delete a template from your Emailit account.

DELETE/templates/:id

Path Parameters

idstringRequired

Template ID (e.g., tem_47TaFwzJx6mD7NeJYvLjFxVwbgT).

DELETE /templates/{id}

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

await emailit.templates.delete('tem_123');

from emailit import EmailitClient
client = EmailitClient("your_api_key")

client.templates.delete("tem_123")

$emailit = Emailit::client('your_api_key');

$emailit->templates()->delete('tem_123');

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

client.templates.delete("tem_123")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

err := client.Templates.Delete("tem_123")

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

emailit.templates.delete("tem_123").await?;

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

emailit.templates().delete("tem_123");

using Emailit;
var emailit = new EmailitClient("your_api_key");

emailit.Templates.Delete("tem_123");

use Emailit\Laravel\Facades\Emailit;

Emailit::templates()->delete('tem_123');

curl -X DELETE https://api.emailit.com/v2/templates/tem_123 \
  -H "Authorization: Bearer your_api_key"

{
  "data": null,
  "message": "Template was successfully deleted."
}

{
  "message": "Template not found"
}

Important Notes

Deleting a published template: If you delete the published template for an alias, no template will be published for that alias until you publish another version using the Publish Template endpoint.
Deleting a draft: Deleting a draft template has no effect on the currently published template for that alias.
This action is irreversible. The template and its content will be permanently deleted.

Publish Template

Publish a template and automatically unpublish all other templates with the same alias. Only one template per alias can be published at any time.

POST/templates/:id/publish

Path Parameters

idstringRequired

Template ID (e.g., tem_47TaFwzJx6mD7NeJYvLjFxVwbgT).

Request Body

Empty body (no parameters required).

POST /templates/{id}/publish

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const template = await emailit.templates.publish('tem_123');

from emailit import EmailitClient
client = EmailitClient("your_api_key")

template = client.templates.publish("tem_123")

$emailit = Emailit::client('your_api_key');

$template = $emailit->templates()->publish('tem_123');

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

template = client.templates.publish("tem_123")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

template, err := client.Templates.Publish("tem_123")

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let template = emailit.templates.publish("tem_123").await?;

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject template = emailit.templates().publish("tem_123");

using Emailit;
var emailit = new EmailitClient("your_api_key");

var template = emailit.Templates.Publish("tem_123");

use Emailit\Laravel\Facades\Emailit;

$template = Emailit::templates()->publish('tem_123');

curl -X POST https://api.emailit.com/v2/templates/tem_123/publish \
  -H "Authorization: Bearer your_api_key"

{
  "data": {
    "id": "tem_anotherOidHere123456789",
    "name": "Welcome Email v2",
    "alias": "welcome-email",
    "from": "Support <support@company.com>",
    "subject": "Welcome! Updated version",
    "reply_to": ["support@company.com"],
    "html": "<h1>Welcome v2!</h1>",
    "text": "Welcome v2!",
    "editor": "html",
    "published_at": "2025-12-24T13:00:00.000000Z",
    "preview_url": null,
    "created_at": "2025-12-24T11:00:00.000000Z",
    "updated_at": "2025-12-24T13:00:00.000000Z"
  },
  "message": "Template was successfully published."
}

{
  "message": "Template not found"
}

How Publishing Works

When you publish a template:

The target template gets its published_at timestamp set to the current time.
All other templates with the same alias have their published_at set to null (unpublished).

This ensures that only one template per alias is ever published, making it easy to manage template versions and switch between them.

Use Cases

A/B Testing: Create multiple versions of a template and publish different versions to test performance.
Rollback: Quickly revert to a previous version by publishing an older template.
Staging: Create new versions as drafts, test them, and publish when ready.