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 templatesDeprecated

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"

query Parameters

paginated	boolean Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.
limit	integer [ 1 .. 500 ] Default: 10 Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.
offset	integer >= 0 Default: 0 Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.

Responses

200

Success

400

Request was not successful

401

Authentication invalid

422

Invalid request parameters

get/templates/{template_type}

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,
"can_edit_body": true,
"can_toggle": true,
"subject": "string",
"markup": "string",
"body": "string",
"available_variables": ["string"
],
"required_variables": ["string"
],
"from_email_name": "string",
"reply_to_email_name": "string",
"delivered_by_clerk": true,
"enabled": true,
"updated_at": 0,
"created_at": 0
}
]

Retrieve a templateDeprecated

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,
"can_edit_body": true,
"can_toggle": true,
"subject": "string",
"markup": "string",
"body": "string",
"available_variables": ["string"
],
"required_variables": ["string"
],
"from_email_name": "string",
"reply_to_email_name": "string",
"delivered_by_clerk": true,
"enabled": true,
"updated_at": 0,
"created_at": 0
}

Update a template for a given type and slugDeprecated

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

403

Request was not successful

404

Resource not found

422

Invalid request parameters

put/templates/{template_type}/{slug}

Request samples

Payload

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,
"can_edit_body": true,
"can_toggle": true,
"subject": "string",
"markup": "string",
"body": "string",
"available_variables": ["string"
],
"required_variables": ["string"
],
"from_email_name": "string",
"reply_to_email_name": "string",
"delivered_by_clerk": true,
"enabled": true,
"updated_at": 0,
"created_at": 0
}

Revert a templateDeprecated

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,
"can_edit_body": true,
"can_toggle": true,
"subject": "string",
"markup": "string",
"body": "string",
"available_variables": ["string"
],
"required_variables": ["string"
],
"from_email_name": "string",
"reply_to_email_name": "string",
"delivered_by_clerk": true,
"enabled": true,
"updated_at": 0,
"created_at": 0
}

Preview changes to a templateDeprecated

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

400

Request was not successful

401

Authentication invalid

404

Resource not found

422

Invalid request parameters

post/templates/{template_type}/{slug}/preview

Request samples

Payload

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 slugDeprecated

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

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

Payload

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,
"can_edit_body": true,
"can_toggle": true,
"subject": "string",
"markup": "string",
"body": "string",
"available_variables": ["string"
],
"required_variables": ["string"
],
"from_email_name": "string",
"reply_to_email_name": "string",
"delivered_by_clerk": true,
"enabled": true,
"updated_at": 0,
"created_at": 0
}

➔ Next to Instance Settings