Clerk docs

Email & SMS Templates

Email & SMS templates allow you to customize the theming and wording of emails & SMS messages that are sent by your instance.

https://clerk.com/docs/authentication/email-sms-templates

List all templates

Returns a list of all templates. The templates are returned sorted by position.

SecuritybearerAuth
Request
path Parameters
template_type
required
string

The type of templates to list (email or SMS)

Enum: "email" "sms"
Responses
200

Success

400

Request was not successful

401

Authentication invalid

422

Invalid request parameters

get/templates/{template_type}
Response samples
application/json
[
  • {
    }
]

Retrieve a template

Returns the details of a template

SecuritybearerAuth
Request
path Parameters
template_type
required
string

The type of templates to retrieve (email or SMS)

Enum: "email" "sms"
slug
required
string

The slug (i.e. machine-friendly name) of the template to retrieve

Responses
200

Success

400

Request was not successful

401

Authentication invalid

404

Resource not found

get/templates/{template_type}/{slug}
Response samples
application/json
{
  • "id": "string",
  • "object": "template",
  • "instance_id": "string",
  • "resource_type": "string",
  • "template_type": "string",
  • "name": "string",
  • "slug": "string",
  • "position": 0,
  • "can_revert": true,
  • "can_delete": true,
  • "subject": "string",
  • "markup": "string",
  • "body": "string",
  • "available_variables": [
    ],
  • "required_variables": [
    ],
  • "from_email_name": "string",
  • "reply_to_email_name": "string",
  • "delivered_by_clerk": true,
  • "updated_at": 0,
  • "created_at": 0
}

Update a template for a given type and slug

Updates the existing template of the given type and slug

SecuritybearerAuth
Request
path Parameters
template_type
required
string

The type of template to update

Enum: "email" "sms"
slug
required
string

The slug of the template to update

Request Body schema: application/json
name
string

The user-friendly name of the template

subject
string or null

The email subject. Applicable only to email templates.

markup
string or null

The editor markup used to generate the body of the template

body
string

The template body before variable interpolation

delivered_by_clerk
boolean or null

Whether Clerk should deliver emails or SMS messages based on the current template

from_email_name
string

The local part of the From email address that will be used for emails. For example, in the address 'hello@example.com', the local part is 'hello'. Applicable only to email templates.

reply_to_email_name
string

The local part of the Reply To email address that will be used for emails. For example, in the address 'hello@example.com', the local part is 'hello'. Applicable only to email templates.

Responses
200

Success

400

Request was not successful

401

Authentication invalid

402

Payment required

404

Resource not found

422

Invalid request parameters

put/templates/{template_type}/{slug}
Request samples
application/json
{
  • "name": "string",
  • "subject": "string",
  • "markup": "string",
  • "body": "string",
  • "delivered_by_clerk": true,
  • "from_email_name": "string",
  • "reply_to_email_name": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "object": "template",
  • "instance_id": "string",
  • "resource_type": "string",
  • "template_type": "string",
  • "name": "string",
  • "slug": "string",
  • "position": 0,
  • "can_revert": true,
  • "can_delete": true,
  • "subject": "string",
  • "markup": "string",
  • "body": "string",
  • "available_variables": [
    ],
  • "required_variables": [
    ],
  • "from_email_name": "string",
  • "reply_to_email_name": "string",
  • "delivered_by_clerk": true,
  • "updated_at": 0,
  • "created_at": 0
}

Revert a template

Reverts an updated template to its default state

SecuritybearerAuth
Request
path Parameters
template_type
required
string

The type of template to revert

Enum: "email" "sms"
slug
required
string

The slug of the template to revert

Responses
200

Success

400

Request was not successful

401

Authentication invalid

402

Payment required

404

Resource not found

post/templates/{template_type}/{slug}/revert
Response samples
application/json
{
  • "id": "string",
  • "object": "template",
  • "instance_id": "string",
  • "resource_type": "string",
  • "template_type": "string",
  • "name": "string",
  • "slug": "string",
  • "position": 0,
  • "can_revert": true,
  • "can_delete": true,
  • "subject": "string",
  • "markup": "string",
  • "body": "string",
  • "available_variables": [
    ],
  • "required_variables": [
    ],
  • "from_email_name": "string",
  • "reply_to_email_name": "string",
  • "delivered_by_clerk": true,
  • "updated_at": 0,
  • "created_at": 0
}

Preview changes to a template

Returns a preview of a template for a given template_type, slug and body

SecuritybearerAuth
Request
path Parameters
template_type
required
string

The type of template to preview

slug
required
string

The slug of the template to preview

Request Body schema: application/json

Required parameters

subject
string or null

The email subject. Applicable only to email templates.

body
string

The template body before variable interpolation

from_email_name
string

The local part of the From email address that will be used for emails. For example, in the address 'hello@example.com', the local part is 'hello'. Applicable only to email templates.

reply_to_email_name
string

The local part of the Reply To email address that will be used for emails. For example, in the address 'hello@example.com', the local part is 'hello'. Applicable only to email templates.

Responses
200

OK

400

Request was not successful

401

Authentication invalid

404

Resource not found

422

Invalid request parameters

post/templates/{template_type}/{slug}/preview
Request samples
application/json
{
  • "subject": "string",
  • "body": "string",
  • "from_email_name": "string",
  • "reply_to_email_name": "string"
}
Response samples
application/json
{ }

Toggle the delivery by Clerk for a template of a given type and slug

Toggles the delivery by Clerk for a template of a given type and slug. If disabled, Clerk will not deliver the resulting email or SMS. The app developer will need to listen to the email.created or sms.created webhooks in order to handle delivery themselves.

SecuritybearerAuth
Request
path Parameters
template_type
required
string

The type of template to toggle delivery for

Enum: "email" "sms"
slug
required
string

The slug of the template for which to toggle delivery

Request Body schema: application/json
delivered_by_clerk
boolean or null

Whether Clerk should deliver emails or SMS messages based on the current template

Responses
200

Success

400

Request was not successful

401

Authentication invalid

404

Resource not found

post/templates/{template_type}/{slug}/toggle_delivery
Request samples
application/json
{
  • "delivered_by_clerk": true
}
Response samples
application/json
{
  • "id": "string",
  • "object": "template",
  • "instance_id": "string",
  • "resource_type": "string",
  • "template_type": "string",
  • "name": "string",
  • "slug": "string",
  • "position": 0,
  • "can_revert": true,
  • "can_delete": true,
  • "subject": "string",
  • "markup": "string",
  • "body": "string",
  • "available_variables": [
    ],
  • "required_variables": [
    ],
  • "from_email_name": "string",
  • "reply_to_email_name": "string",
  • "delivered_by_clerk": true,
  • "updated_at": 0,
  • "created_at": 0
}
➔ Next to Instance Settings