Custom Email Templates

These endpoints allow you to programmatically manage email customizations.

Okta provides many customizable email templates. For example, the UserActivation email template allows users to activate their account. Use email customizations to override a template's default content. See the list of email templates.

Each template has default content that Okta translates to any one of the supported languages. The following settings determine the language for emails sent from Okta to a user, if the user hasn't selected a specific display language:

  • The user's locale property value (if specified)
  • The org's display language

See Supported languages.

The following constraints apply to email customizations:

  • If an email template has any customizations at all, exactly one of them must be the default (where isDefault is true). Okta uses the default customization when no other customization applies to the user's language settings.
  • Each email template can have only one customization for each supported language.

Enable other locales

Use the BCP 47 format to enable more locales than Okta's 27 default languages.

Once you create a customization with the new locale, the locale appears in the Admin Console along with the default-supported locales.

Include null in the subject or body of the email customization. Okta replaces null with a default value based on the following order of priority:

  • An existing default email customization, if one exists
  • Okta-provided translated content for the specified language, if one exists
  • Okta-provided translated content for the brand locale, if it's set
  • Okta-provided content in English

List all Email Templates
OAuth 2.0: okta.templates.read

Lists all supported email templates

Request
path Parameters
brandId
required
string

The ID of the brand

query Parameters
after
string

The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination.

limit
integer [ 1 .. 200 ]
Default: 20

A limit on the number of objects to return

expand
Array of strings

Specifies additional metadata to be included in the response

Items Enum: "settings" "customizationCount"
Responses
200

Successfully returned the list of email templates.

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/brands/{brandId}/templates/email
Request samples 
Response samples 
application/json
[]
Retrieve an Email Template
OAuth 2.0: okta.templates.read
Retrieves the details of an email template by name


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Enum: "settings" "customizationCount"  
Responses 
200
Successfully retrieved the email template.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}
Request samples 
Response samples 
application/json
{}
List all Email Customizations
OAuth 2.0: okta.templates.read
Lists all customizations of an email template


 If Custom languages for Okta Email Templates is enabled, all existing customizations are retrieved, including customizations for additional languages. If disabled, only customizations for Okta-supported languages are returned.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
query Parameters
after
string
The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination.


 
limit
integer  [ 1 .. 200 ] 
 Default:  20
A limit on the number of objects to return


 
Responses 
200
Successfully retrieved all email customizations for the specified email template.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/customizations
Request samples 
Response samples 
application/json
[]
Create an Email Customization
OAuth 2.0: okta.templates.manage
Creates a new Email Customization


 If Custom languages for Okta Email Templates is enabled, you can create a customization for any BCP47 language in addition to the Okta-supported languages.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
Request Body schema: application/json
subject
required
string
The email subject. May contain variable references.


 Not required if Custom languages for Okta Email Templates is enabled. A null subject is replaced with a default value from one of the following in priority order:


    

  1. An existing default email customization, if one exists
    2. 

  2. Okta-provided translated content for the specified language, if one exists
    3. 

  3. Okta-provided translated content for the brand locale, if it's set
    4. 

  4. Okta-provided content in English
    5. 



 
body
required
string
The HTML body of the email. May contain variable references. 


 Not required if Custom languages for Okta Email Templates is enabled. A null body is replaced with a default value from one of the following in priority order:


    

  1. An existing default email customization, if one exists
    2. 

  2. Okta-provided translated content for the specified language, if one exists
    3. 

  3. Okta-provided translated content for the brand locale, if it's set 
    4. 

  4. Okta-provided content in English
    5. 



 
language
required
string (Language) 
The language specified as an IETF BCP 47 language tag


 
isDefault
boolean
Whether this is the default customization for the email template. Each customized email template must have exactly one default customization. Defaults to true for the first customization and false thereafter.


 
Responses 
201
Successfully created the email customization.


400
Bad Request


403
Forbidden


404
Not Found


409
Could not create the email customization because it conflicts with an existing email customization.


429
Too Many Requests


post/api/v1/brands/{brandId}/templates/email/{templateName}/customizations
Request samples 
application/json
{
  • "language": "fr",
  • "subject": "Bienvenue dans ${org.name}!",
  • "body": "<!DOCTYPE html><html><body><p>Bonjour ${user.profile.firstName}. <a href=\"${activationLink}\">Activer le compte</a></p></body></html>",
  • "isDefault": false
}
Response samples 
application/json
{}
Delete all Email Customizations
OAuth 2.0: okta.templates.manage
Deletes all customizations for an email template


 If Custom languages for Okta Email Templates is enabled, all customizations are deleted, including customizations for additional languages. If disabled, only customizations in Okta-supported languages are deleted.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
Responses 
204
Successfully deleted all customizations for the email template.


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/brands/{brandId}/templates/email/{templateName}/customizations
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Retrieve an Email Customization
OAuth 2.0: okta.templates.read
Retrieves an email customization by its unique identifier


 If Custom languages for Okta Email Templates is disabled, requests to retrieve an additional language customization by ID result in a 404 Not Found error response.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
customizationId
required
string
The ID of the email customization


 
Responses 
200
Successfully retrieved the email customization.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/customizations/{customizationId}
Request samples 
Response samples 
application/json
{}
Replace an Email Customization
OAuth 2.0: okta.templates.manage
Replaces an email customization using property values


 If Custom languages for Okta Email Templates is disabled, requests to update a customization for an additional language return a 404 Not Found error response.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
customizationId
required
string
The ID of the email customization


 
Request Body schema: application/json
Request


subject
required
string
The email subject. May contain variable references.


 Not required if Custom languages for Okta Email Templates is enabled. A null subject is replaced with a default value from one of the following in priority order:


    

  1. An existing default email customization, if one exists
    2. 

  2. Okta-provided translated content for the specified language, if one exists
    3. 

  3. Okta-provided translated content for the brand locale, if it's set
    4. 

  4. Okta-provided content in English
    5. 



 
body
required
string
The HTML body of the email. May contain variable references. 


 Not required if Custom languages for Okta Email Templates is enabled. A null body is replaced with a default value from one of the following in priority order:


    

  1. An existing default email customization, if one exists
    2. 

  2. Okta-provided translated content for the specified language, if one exists
    3. 

  3. Okta-provided translated content for the brand locale, if it's set 
    4. 

  4. Okta-provided content in English
    5. 



 
language
required
string (Language) 
The language specified as an IETF BCP 47 language tag


 
isDefault
boolean
Whether this is the default customization for the email template. Each customized email template must have exactly one default customization. Defaults to true for the first customization and false thereafter.


 
Responses 
200
Successfully updated the email customization.


400
Bad Request


403
Forbidden


404
Not Found


409
Could not update the email customization because the update would cause a conflict with an existing email customization.


429
Too Many Requests


put/api/v1/brands/{brandId}/templates/email/{templateName}/customizations/{customizationId}
Request samples 
application/json
{
  • "language": "fr",
  • "subject": "Bienvenue dans ${org.name}!",
  • "body": "<!DOCTYPE html><html><body><p>Bonjour ${user.profile.firstName}. <a href=\"${activationLink}\">Activer le compte</a></p></body></html>",
  • "isDefault": false
}
Response samples 
application/json
{}
Delete an Email Customization
OAuth 2.0: okta.templates.manage
Deletes an Email Customization by its unique identifier


 If Custom languages for Okta Email Templates is disabled, deletion of an existing additional language customization by ID doesn't register.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
customizationId
required
string
The ID of the email customization


 
Responses 
204
Successfully deleted the email customization.


403
Forbidden


404
Not Found


409
Could not delete the email customization deleted because it is the default email customization.


429
Too Many Requests


delete/api/v1/brands/{brandId}/templates/email/{templateName}/customizations/{customizationId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Retrieve a Preview of an Email Customization
OAuth 2.0: okta.templates.read
Retrieves a Preview of an Email Customization. All variable references are populated from the current user's context. For example, ${user.profile.firstName}.


 If Custom languages for Okta Email Templates is disabled, requests for the preview of an additional language customization by ID return a 404 Not Found error response.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
customizationId
required
string
The ID of the email customization


 
Responses 
200
Successfully generated a preview of the email customization.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/customizations/{customizationId}/preview
Request samples 
Response samples 
application/json
{}
Retrieve an Email Template Default Content
OAuth 2.0: okta.templates.read
Retrieves an email template's default content


 Defaults to the current user's language given the following: 


    

  • Custom languages for Okta Email Templates is enabled
    • 

  • An additional language is specified for the language parameter
    • 



Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
query Parameters
language
string (Language) 
The language to use for the email. Defaults to the current user's language if unspecified.


 
Responses 
200
Successfully retrieved the email template's default content.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/default-content
Request samples 
Response samples 
application/json
{}
Retrieve a Preview of the Email Template default content
OAuth 2.0: okta.templates.read
Retrieves a preview of an Email Template's default content. All variable references are populated using the current user's context. For example, ${user.profile.firstName}.


 Defaults to the current user's language given the following:


    

  • Custom languages for Okta Email Templates is enabled
    • 

  • An additional language is specified for the language parameter
    • 



Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
query Parameters
language
string (Language) 
The language to use for the email. Defaults to the current user's language if unspecified.


 
Responses 
200
Successfully generated a preview of the email template's default content.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/default-content/preview
Request samples 
Response samples 
application/json
{}
Retrieve the Email Template Settings
OAuth 2.0: okta.templates.read
Retrieves an email template's settings


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
Responses 
200
Successfully retrieved the email template's settings.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/settings
Request samples 
Response samples 
application/json
{}
Replace the Email Template Settings
OAuth 2.0: okta.templates.manage
Replaces an email template's settings


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
Request Body schema: application/json
recipients
required
string
 Enum: "ALL_USERS" "ADMINS_ONLY" "NO_USERS"  
Responses 
200
Successfully updated the email template's settings.


400
Bad Request


403
Forbidden


404
Not Found


422
Could not update the email template's settings due to an invalid setting value.


429
Too Many Requests


put/api/v1/brands/{brandId}/templates/email/{templateName}/settings
Request samples 
application/json
{
  • "recipients": "ALL_USERS"
}
Response samples 
application/json
{}
Send a Test Email
OAuth 2.0: okta.templates.read
Sends a test email to the current user’s primary and secondary email addresses. The email content is selected based on the following priority:


    

  1. The email customization for the language specified in the language query parameter.
 If Custom languages for Okta Email Templates is enabled and the language parameter is an additional language, the test email uses the customization corresponding to the language.
    2. 

  2. The email template's default customization.
    3. 

  3. The email template’s default content, translated to the current user's language.
    4. 



Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
query Parameters
language
string (Language) 
The language to use for the email. Defaults to the current user's language if unspecified.


 
Responses 
204
Successfully sent a test email.


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/brands/{brandId}/templates/email/{templateName}/test
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}