Logto Email templates API
Manage custom i18n email templates for various types of emails, such as sign-in verification codes and password resets.
OpenAPI Specification
openapi: 3.0.1
info:
title: Logto API references Account center Email templates API
description: 'API references for Logto services.
Note: The documentation is for Logto Cloud. If you are using Logto OSS, please refer to the response of `/api/swagger.json` endpoint on your Logto instance.'
version: Cloud
servers:
- url: https://[tenant_id].logto.app/
description: Logto endpoint address.
security:
- OAuth2:
- all
tags:
- name: Email templates
description: Manage custom i18n email templates for various types of emails, such as sign-in verification codes and password resets.
paths:
/api/email-templates:
put:
operationId: ReplaceEmailTemplates
tags:
- Email templates
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- templates
properties:
templates:
type: array
items:
type: object
required:
- languageTag
- templateType
- details
properties:
languageTag:
type: string
minLength: 1
maxLength: 16
description: The language tag of the email template, e.g., `en` or `fr`.
templateType:
type: string
enum:
- SignIn
- Register
- ForgotPassword
- OrganizationInvitation
- Generic
- UserPermissionValidation
- BindNewIdentifier
- MfaVerification
- BindMfa
description: The type of the email template, e.g. `SignIn` or `ForgotPassword`
details:
type: object
required:
- subject
- content
properties:
subject:
type: string
description: The template of the email subject.
content:
type: string
description: The template of the email body.
contentType:
oneOf:
- type: string
format: '"text/html"'
- type: string
format: '"text/plain"'
description: The content type of the email body. (Only required by some specific email providers.)
replyTo:
type: string
description: The reply name template of the email. If not provided, the target email address will be used. (The render logic may differ based on the email provider.)
sendFrom:
type: string
description: The send from name template of the email. If not provided, the default Logto email address will be used. (The render logic may differ based on the email provider.)
description: The details of the email template.
responses:
'200':
description: The list of newly created or replaced email templates.
content:
application/json:
schema:
type: array
items:
type: object
required:
- tenantId
- id
- languageTag
- templateType
- details
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
languageTag:
type: string
minLength: 1
maxLength: 16
templateType:
type: string
enum:
- SignIn
- Register
- ForgotPassword
- OrganizationInvitation
- Generic
- UserPermissionValidation
- BindNewIdentifier
- MfaVerification
- BindMfa
details:
type: object
required:
- subject
- content
properties:
subject:
type: string
content:
type: string
contentType:
oneOf:
- type: string
format: '"text/html"'
- type: string
format: '"text/plain"'
replyTo:
type: string
sendFrom:
type: string
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Unprocessable Content
summary: Replace email templates
description: Create or replace a list of email templates. If an email template with the same language tag and template type already exists, its details will be updated.
get:
operationId: ListEmailTemplates
tags:
- Email templates
parameters:
- name: languageTag
in: query
required: false
schema:
type: string
minLength: 1
maxLength: 16
description: The language tag of the email template, e.g., `en` or `fr`.
- name: templateType
in: query
required: false
schema:
type: string
enum:
- SignIn
- Register
- ForgotPassword
- OrganizationInvitation
- Generic
- UserPermissionValidation
- BindNewIdentifier
- MfaVerification
- BindMfa
description: The type of the email template, e.g. `SignIn` or `ForgotPassword`
responses:
'200':
description: The list of matched email templates. Returns empty list, if no email template is found.
content:
application/json:
schema:
type: array
items:
type: object
required:
- tenantId
- id
- languageTag
- templateType
- details
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
languageTag:
type: string
minLength: 1
maxLength: 16
templateType:
type: string
enum:
- SignIn
- Register
- ForgotPassword
- OrganizationInvitation
- Generic
- UserPermissionValidation
- BindNewIdentifier
- MfaVerification
- BindMfa
details:
type: object
required:
- subject
- content
properties:
subject:
type: string
content:
type: string
contentType:
oneOf:
- type: string
format: '"text/html"'
- type: string
format: '"text/plain"'
replyTo:
type: string
sendFrom:
type: string
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Get email templates
description: Get the list of email templates.
delete:
operationId: DeleteEmailTemplates
tags:
- Email templates
parameters:
- name: languageTag
in: query
required: false
schema:
type: string
minLength: 1
maxLength: 16
description: The language tag of the email template, e.g., `en` or `fr`.
- name: templateType
in: query
required: false
schema:
type: string
enum:
- SignIn
- Register
- ForgotPassword
- OrganizationInvitation
- Generic
- UserPermissionValidation
- BindNewIdentifier
- MfaVerification
- BindMfa
description: The type of the email template, e.g. `SignIn` or `ForgotPassword`
responses:
'200':
description: The email templates were deleted successfully.
content:
application/json:
schema:
type: object
required:
- rowCount
properties:
rowCount:
type: number
description: The number of email templates deleted.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: No filter query parameters were provided. This bulk deletion API requires at least one filter query parameter.
summary: Delete email templates
description: Bulk delete email templates by their language tag and template type.
/api/email-templates/{id}:
get:
operationId: GetEmailTemplate
tags:
- Email templates
parameters:
- $ref: '#/components/parameters/emailTemplateId-root'
responses:
'200':
description: The email template.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- languageTag
- templateType
- details
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
languageTag:
type: string
minLength: 1
maxLength: 16
templateType:
type: string
enum:
- SignIn
- Register
- ForgotPassword
- OrganizationInvitation
- Generic
- UserPermissionValidation
- BindNewIdentifier
- MfaVerification
- BindMfa
details:
type: object
required:
- subject
- content
properties:
subject:
type: string
content:
type: string
contentType:
oneOf:
- type: string
format: '"text/html"'
- type: string
format: '"text/plain"'
replyTo:
type: string
sendFrom:
type: string
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The email template was not found.
summary: Get email template by ID
description: Get the email template by its ID.
delete:
operationId: DeleteEmailTemplate
tags:
- Email templates
parameters:
- $ref: '#/components/parameters/emailTemplateId-root'
responses:
'204':
description: The email template was deleted successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The email template was not found.
summary: Delete an email template
description: Delete an email template by its ID.
/api/email-templates/{id}/details:
patch:
operationId: UpdateEmailTemplateDetails
tags:
- Email templates
parameters:
- $ref: '#/components/parameters/emailTemplateId-root'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
subject:
type: string
description: The template of the email subject.
content:
type: string
description: The template of the email body.
contentType:
oneOf:
- type: string
format: '"text/html"'
- type: string
format: '"text/plain"'
description: The content type of the email body. (Only required by some specific email providers.)
replyTo:
type: string
description: The reply name template of the email. If not provided, the target email address will be used. (The render logic may differ based on the email provider.)
sendFrom:
type: string
description: The send from name template of the email. If not provided, the default Logto email address will be used. (The render logic may differ based on the email provider.)
responses:
'200':
description: The updated email template.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- languageTag
- templateType
- details
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
languageTag:
type: string
minLength: 1
maxLength: 16
templateType:
type: string
enum:
- SignIn
- Register
- ForgotPassword
- OrganizationInvitation
- Generic
- UserPermissionValidation
- BindNewIdentifier
- MfaVerification
- BindMfa
details:
type: object
required:
- subject
- content
properties:
subject:
type: string
content:
type: string
contentType:
oneOf:
- type: string
format: '"text/html"'
- type: string
format: '"text/plain"'
replyTo:
type: string
sendFrom:
type: string
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: The email template was not found.
summary: Update email template details
description: Update the details of an email template by its ID.
components:
parameters:
emailTemplateId-root:
in: path
description: The unique identifier of the email template.
required: true
schema:
type: string
name: id
securitySchemes:
OAuth2:
type: oauth2
description: "Logto Management API is a comprehensive set of REST APIs that gives you the full control over Logto to suit your product needs and tech stack. To see the full guide on Management API interactions, visit [Interact with Management API](https://docs.logto.io/docs/recipes/interact-with-management-api/).\n\n### Get started\n\nThe API follows the same authentication principles as other API resources in Logto, with some slight differences. To use Logto Management API:\n\n1. A machine-to-machine (M2M) application needs to be created.\n2. A machine-to-machine (M2M) role with Management API permission `all` needs to be assigned to the application.\n\nOnce you have them set up, you can use the `client_credentials` grant type to fetch an access token and use it to authenticate your requests to the Logto Management API.\n\n### Fetch an access token\n\nTo fetch an access token, you need to make a `POST` request to the `/oidc/token` endpoint of your Logto tenant.\n\nFor Logto Cloud users, the base URL is your Logto endpoint, i.e. `https://[tenant-id].logto.app`. The tenant ID can be found in the following places:\n\n- The first path segment of the URL when you are signed in to Logto Cloud. For example, if the URL is `https://cloud.logto.io/foo/get-started`, the tenant ID is `foo`.\n- In the \"Settings\" tab of Logto Cloud.\n\nThe request should follow the OAuth 2.0 [client credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) grant type. Here is a non-normative example of how to fetch an access token:\n\n```bash\ncurl --location \\\n --request POST 'https://[tenant-id].logto.app/oidc/token' \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'grant_type=client_credentials' \\\n --data-urlencode 'client_id=[app-id]' \\\n --data-urlencode 'client_secret=[app-secret]' \\\n --data-urlencode 'resource=https://[tenant-id].logto.app/api' \\\n --data-urlencode 'scope=all'\n```\n\nReplace `[tenant-id]`, `[app-id]`, and `[app-secret]` with your Logto tenant ID, application ID, and application secret, respectively.\n\nThe response will be like:\n\n```json\n{\n \"access_token\": \"eyJhbG...2g\", // Use this value for accessing the Logto Management API\n \"expires_in\": 3600, // Token expiration in seconds\n \"token_type\": \"Bearer\", // Token type for your request when using the access token\n \"scope\": \"all\" // Scope `all` for Logto Management API\n}\n```\n\n### Use the access token\n\nOnce you have the access token, you can use it to authenticate your requests to the Logto Management API. The access token should be included in the `Authorization` header of your requests with the `Bearer` authentication scheme.\n\nHere is an example of how to list the first page of users in your Logto tenant:\n\n```bash\ncurl --location \\\n --request GET 'https://[tenant-id].logto.app/api/users' \\\n --header 'Authorization: Bearer eyJhbG...2g'\n```\n\nReplace `[tenant-id]` with your Logto tenant ID and `eyJhbG...2g` with the access token you fetched earlier."
flows:
clientCredentials:
tokenUrl: /oidc/token
scopes:
all: All scopes