Skip to content
Docs

Create template versions, publish one per alias, and use them when sending.

Base URLhttps://api.emailit.com/v2AuthenticationErrorsRate limits

Create a template

Creates a template version. Versions that share an alias belong to the same template, and only one version per alias is published at a time. When you send an email with template set to an alias, Emailit uses the published version. Requires an API key with full scope.

POST/templates

Request body

namestringRequired

Template name shown in the dashboard. Up to 191 characters.

aliasstringRequired

Identifier that groups the versions of a template. Up to 191 characters; lowercase letters, numbers, underscores and hyphens only (^[a-z0-9_-]+$).

If no template uses this alias yet, the new version is published immediately. If the alias already exists, the new version is created unpublished (published_at is null) and you publish it with Publish a template.

fromstring

Default sender, for example Acme <hello@acme.com>. Up to 191 characters.

subjectstring

Default subject line. Up to 191 characters. Can contain Temple variables such as {{ first_name }}.

reply_tostring | string[]

Reply-to address, or an array of addresses. Every value must be a valid email address.

htmlstring

HTML body.

textstring

Plain-text body.

sourcestring

Editor source document, for example the Dragit JSON of a template built in the drag-and-drop editor. Stored as-is. For editor: "mjml", the MJML: Emailit validates it, stores it as an MJML document and compiles html from it.

editorstring

Editor the template belongs to: html (default), text, dragit or tiptap. mjml is in alpha and open to the Emailit team only; other requests get 403 with error: "mjml_alpha". See MJML editors and API.

Returns

Returns 201 Created with the template in data and a confirmation message. The template includes html, text and source. Emailit also sends a template.created webhook event.

MJML templates also return an mjml object with the document’s versions. Invalid MJML returns 422 with errors.source and diagnostics; see Validation.

If a field fails validation, the response is 400 with message: "Validation failed" and an errors object keyed by field, for example an alias with uppercase letters or an invalid reply_to address. A missing name or alias, or an editor value that isn’t allowed, returns the standard 400 validation error with a details array instead. See Errors.

POST/templates
Terminal
curl https://api.emailit.com/v2/templates \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome email",
    "alias": "welcome-email",
    "subject": "Welcome to Acme, {{ first_name }}",
    "html": "<h1>Welcome, {{ first_name }}</h1>"
  }'
JSON
{
  "data": {
    "id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
    "name": "Welcome email",
    "alias": "welcome-email",
    "from": null,
    "subject": "Welcome to Acme, {{ first_name }}",
    "reply_to": null,
    "html": "<h1>Welcome, {{ first_name }}</h1>",
    "text": null,
    "source": null,
    "editor": "html",
    "published_at": "2026-09-30T10:30:00.482119Z",
    "preview_url": null,
    "created_at": "2026-09-30T10:30:00.482119Z",
    "updated_at": "2026-09-30T10:30:00.482119Z"
  },
  "message": "Template was successfully created."
}

Retrieve a template

Returns one template version, including its content, and lists the other versions of the same alias in versions. Templates are looked up by ID only, not by alias. Requires an API key with full scope.

GET/templates/:id

Path parameters

idstringRequired

Template ID, for example tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a.

Returns

Returns 200 OK with the template in data. Besides the template fields, the response has a versions array with the id, name, published_at, created_at and updated_at of every other version that shares the alias, newest first. The published version is the one with a non-null published_at.

Returns 404 with message: "Template not found" if the ID doesn’t exist in your workspace.

GET/templates/{id}
Terminal
curl https://api.emailit.com/v2/templates/tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": {
    "id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
    "name": "Welcome email",
    "alias": "welcome-email",
    "from": "Acme <hello@acme.com>",
    "subject": "Welcome to Acme, {{ first_name }}",
    "reply_to": ["support@acme.com"],
    "html": "<h1>Welcome, {{ first_name }}</h1>",
    "text": "Welcome, {{ first_name }}",
    "source": null,
    "editor": "html",
    "published_at": "2026-09-30T10:30:00.482119Z",
    "preview_url": null,
    "created_at": "2026-09-28T08:12:45.103882Z",
    "updated_at": "2026-09-30T10:30:00.482119Z",
    "versions": [
      {
        "id": "tem_2xKyB4qLm7RtV9sNd3HwEa6uC1f",
        "name": "Welcome email (October)",
        "published_at": null,
        "created_at": "2026-09-30T14:02:11.550731Z",
        "updated_at": "2026-09-30T14:02:11.550731Z"
      }
    ]
  }
}

Update a template

Updates one template version. Send only the fields you want to change. The version keeps its publish state: a published version stays published and a draft stays a draft. Requires an API key with full scope.

POST/templates/:id

Path parameters

idstringRequired

Template ID, for example tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a.

Request body

namestring

Template name. Up to 191 characters.

aliasstring

New alias. Up to 191 characters; lowercase letters, numbers, underscores and hyphens only. It can’t be an alias that another template already uses.

fromstring

Default sender, for example Acme <hello@acme.com>. Up to 191 characters. Send an empty string to clear it.

subjectstring

Default subject line. Up to 191 characters. Send an empty string to clear it.

reply_tostring | string[]

Reply-to address or array of addresses. Send an empty string to clear it.

htmlstring

HTML body.

textstring

Plain-text body.

sourcestring

Editor source document, for example Dragit JSON. For an MJML template, the full MJML: Emailit validates it and recompiles html, and any html you send is ignored.

editorstring

html, text, dragit or tiptap. mjml is in alpha and open to the Emailit team only; changing an MJML template’s content without MJML access returns 403 with error: "mjml_alpha". Renaming or publishing it works for everyone. See MJML editors and API.

Returns

Returns 200 OK with the updated template in data and a confirmation message. Emailit also sends a template.updated webhook event.

Returns 400 with message: "Validation failed" and an errors object when a value is invalid, for example "Alias already exists". Values longer than 191 characters or an unknown editor return the standard 400 validation error. Returns 404 if the template doesn’t exist.

To make this version the one used for sending, call Publish a template.

POST/templates/{id}
Terminal
curl -X POST https://api.emailit.com/v2/templates/tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Welcome aboard, {{ first_name }}"}'
JSON
{
  "data": {
    "id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
    "name": "Welcome email",
    "alias": "welcome-email",
    "from": "Acme <hello@acme.com>",
    "subject": "Welcome aboard, {{ first_name }}",
    "reply_to": ["support@acme.com"],
    "html": "<h1>Welcome, {{ first_name }}</h1>",
    "text": "Welcome, {{ first_name }}",
    "source": null,
    "editor": "html",
    "published_at": "2026-09-30T10:30:00.482119Z",
    "preview_url": null,
    "created_at": "2026-09-28T08:12:45.103882Z",
    "updated_at": "2026-10-01T09:15:27.640000Z"
  },
  "message": "Template was successfully updated."
}

List templates

Returns the published version of each template, newest first. Unpublished versions aren’t listed; retrieve a template to see all versions of its alias. Requires an API key with full scope.

GET/templates

Query parameters

pageinteger

Page number, starting at 1. Default 1.

per_pageinteger

Templates per page, from 1 to 100. Default 25.

include_contentboolean

Set to true to include html, text and source on each template. Omitted by default to keep responses small.

filter[name]string

Case-insensitive partial match on the template name or alias.

filter[alias]string

Exact alias.

filter[editor]string

Editor: html, text, dragit, tiptap or mjml (alpha).

matchstring

all (default) requires every key.condition filter to match. or matches any of them. See Filtering.

sortstring

Sort key: name, alias, created_at (default), updated_at or published_at.

orderstring

Sort direction: asc or desc (default).

Filters

List filters are one layer of key.condition=value query parameters. See Filtering for match, order, direction and the condition list per type.

Filter keys

KeyTypeConditionsNotes
namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
aliasstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
editorstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
subjectstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Sort keys

This endpoint sorts with sort set to one of these keys and order set to asc or desc (order=<key> returns 400 here): name, alias, editor, subject, created_at

On this endpoint, order only accepts asc or desc. Pass the sort key in sort, for example sort=name&order=asc.

Returns

Returns 200 OK with the templates in data and the pagination fields total_records, per_page, current_page and total_pages. Each template includes total_versions, the number of versions that share its alias.

GET/templates
Terminal
curl https://api.emailit.com/v2/templates \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": [
    {
      "id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
      "name": "Welcome email",
      "alias": "welcome-email",
      "from": "Acme <hello@acme.com>",
      "subject": "Welcome to Acme, {{ first_name }}",
      "reply_to": ["support@acme.com"],
      "editor": "html",
      "published_at": "2026-09-30T10:30:00.482119Z",
      "preview_url": null,
      "total_versions": 3,
      "created_at": "2026-09-28T08:12:45.103882Z",
      "updated_at": "2026-09-30T10:30:00.482119Z"
    }
  ],
  "total_records": 1,
  "per_page": 25,
  "current_page": 1,
  "total_pages": 1
}

Publish a template

Publishes a template version and unpublishes every other version with the same alias, in one transaction. Use it to roll out a new draft or to roll back to an earlier version. Requires an API key with full scope.

POST/templates/:id/publish

Path parameters

idstringRequired

ID of the version to publish, for example tem_2xKyB4qLm7RtV9sNd3HwEa6uC1f.

Request body

No body. Publishing an already published version sets a new published_at.

Returns

Returns 200 OK with the published template in data and a confirmation message. Returns 404 if the template doesn’t exist.

Emailit sends a template.updated webhook event for the version you published and one for each version that was unpublished.

POST/templates/{id}/publish
Terminal
curl -X POST https://api.emailit.com/v2/templates/tem_2xKyB4qLm7RtV9sNd3HwEa6uC1f/publish \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": {
    "id": "tem_2xKyB4qLm7RtV9sNd3HwEa6uC1f",
    "name": "Welcome email (October)",
    "alias": "welcome-email",
    "from": "Acme <hello@acme.com>",
    "subject": "Welcome to Acme, {{ first_name }}",
    "reply_to": ["support@acme.com"],
    "html": "<h1>Welcome, {{ first_name }}</h1><p>Here is your October guide.</p>",
    "text": "Welcome, {{ first_name }}. Here is your October guide.",
    "source": null,
    "editor": "html",
    "published_at": "2026-10-01T09:20:04.118502Z",
    "preview_url": null,
    "created_at": "2026-09-30T14:02:11.550731Z",
    "updated_at": "2026-10-01T09:20:04.118000Z"
  },
  "message": "Template was successfully published."
}

Delete a template

Permanently deletes one template version. Other versions of the same alias are kept. Requires an API key with full scope.

DELETE/templates/:id

Path parameters

idstringRequired

Template ID, for example tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a.

Returns

Returns 200 OK with data: null and a confirmation message. Emailit sends a template.deleted webhook event with the deleted version. Returns 404 if the template doesn’t exist.

If you delete the published version, no version of that alias is published until you publish another one, and sending with that alias fails. Deleting a draft doesn’t affect the published version. You can’t undo a delete.

DELETE/templates/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/templates/tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": null,
  "message": "Template was successfully deleted."
}

Was this page helpful?

Thanks for the feedback.

Thanks, we read every message.