Skip to content

Get email template

GET
/api/v1/admin/email-templates/{email}
Code sample: Shell / cURL
curl --request GET \
--url http://localhost:9090/api/v1/admin/email-templates/password_reset_link \
--header 'Authorization: Bearer <token>'

One email: the placeholders it offers, whether it has a button, and for each language the built-in text, the editor’s text, the fields its edit holds, its status and an invalid edit’s problems. The editor’s text is the edit laid over the built-in text, as last saved, also when it is invalid. The email is sent with the editor’s text unless the status is invalid, when it is sent with the built-in text.

email
required
string
Allowed values: password_reset_link activation_link welcome registration_existing_account new_user_setup verification_code test email_address_changed password_changed password_changed_by_administrator password_reset otp_enabled otp_disabled otp_disabled_by_administrator otp_lockout recovery_code_used recovery_codes_replaced account_deleted account_deleted_by_administrator

The email’s identifier

Email template details

Media typeapplication/json
object
emailTemplate
required
object
id
required

The email’s identifier, such as password_reset_link.

string
hasButton
required

Whether the email offers {{button}}, and so has a button label.

boolean
placeholders
required
Array<object>
object
name
required

The name written between double braces, such as name for {{name}}.

string
required
required

Whether the body must use it.

boolean
inSubject
required

Whether the subject may use it. link and button are for the body only.

boolean
languages
required

The six built-in languages, English first.

Array<object>
object
language
required
string
Allowed values: en de es fr it pt-BR
status
required

default with no edit, edited when the edit is sent, and invalid when the edit breaks a rule of the running release, so the built-in text is sent instead.

string
Allowed values: default edited invalid
builtInText
required
object
subject
required
string
buttonLabel

Present for an email with a button.

string
body
required
string
editorText
required
object
subject
required
string
buttonLabel

Present for an email with a button.

string
body
required
string
editedFields
required

The fields the edit holds, empty with no edit.

Array<string>
Allowed values: subject buttonLabel body
problems
required

The rules an invalid edit breaks, empty otherwise.

Array<object>
object
field
required
string
Allowed values: subject buttonLabel body
rule
required

The rule broken: unknown_placeholder, required_placeholder_missing, placeholder_not_in_subject, button_not_alone, placeholder_in_link_destination, nothing_to_read, empty, too_long, not_one_line or no_button.

string
placeholder

The placeholder the rule is about, as written between the braces.

string
message
required

The sentence a save refuses the text with, in the request’s language.

string

Example

{
"emailTemplate": {
"languages": [
{
"language": "en",
"status": "default",
"editedFields": [
"subject"
],
"problems": [
{
"field": "subject"
}
]
}
]
}
}

Missing or invalid access token (ACCESS_TOKEN_REQUIRED, INVALID_TOKEN), or a refused DPoP proof (INVALID_DPOP_PROOF)

Media typeapplication/json

Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.

object
error_code

Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.

string
error_description
required

A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.

string
error_field

A JSON Pointer (RFC 6901) to the member of the request body the refusal is about, such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand. Left out when the refusal names no member. It’s set by the refusals of a brand’s footer links, palette and custom CSS, and of an email template’s text and brandId.

string

Example generated

{
"error_code": "example",
"error_description": "example",
"error_field": "example"
}
WWW-Authenticate
string

A Bearer challenge, then a DPoP challenge naming the accepted proof algorithms, on token refusals, the error in the challenge of the scheme the token was sent with: Bearer realm="goiabada", error="invalid_token", error_description="...", DPoP realm="goiabada", algs="ES256 ...". An operation may also return a handler-level 401 without this header.

The token is valid but does not authorise this request. A caller tells the refusals apart by error_code.

INSUFFICIENT_SCOPE comes from the route’s authorisation middleware, before the handler runs: an Admin operation needs one of the scopes its route names, and an Account operation needs authserver:manage-account.

USER_CONTEXT_REQUIRED comes from the same middleware on the Account operations, which also require the token to have been issued for a user: one obtained through the client credentials grant carries no auth_time claim and is refused here.

FORBIDDEN comes from the handler, on the account endpoints that resolve a resource by id and then check it belongs to the caller, so a valid token for the wrong user reaches this rather than a 404.

CLIENT_NOT_ALLOWED comes from the route on the two Account operations only the admin console’s own client may call, deleteAccount and exportAccount. ACCOUNT_DELETION_DISABLED comes from deleteAccount while an administrator has turned off Let users delete their own account.

MANAGE_SCOPE_REQUIRED comes from the handler, on the Admin operations the administrative policy guards. Only authserver:manage creates an administrator, changes one, or changes what reaches one, so no granular scope will ever be enough: the remedy is a token holding authserver:manage, not requesting the route’s scope as for INSUFFICIENT_SCOPE. An administrator is a user, group or client holding any of the six administrative permissions (manage, admin-read, manage-users, manage-clients, manage-settings, browser-sessions), a user directly or through any of its groups, the admin console’s own client whatever it holds, and a client allowed to request the administrative scopes. A granular scope is refused here when it:

  • grants or revokes an administrative permission, directly or by moving a user into or out of a group that holds one, or deletes such a group;
  • writes to an administrator user (profile, credentials, enabled, sessions, consents, attributes, memberships, permissions, deletion), an administrative group (settings, attributes, members, permissions, deletion), or an administrator client (settings, authentication, flows, redirect URIs, sign-out redirect URIs, back-channel logout, DPoP, web origins, token settings, permissions, introspection resources, logo, deletion);
  • switches whether a client may request the administrative scopes, on or off, on any client;
  • adds the authserver resource to a client’s introspection resources;
  • reads an administrator client’s secret, or reads or sets the secret of a client listed for the authserver resource among its introspection resources;
  • sets or changes a client’s back-channel logout URI;
  • changes the email or the audit-log settings;
  • changes an administrative permission’s description. Granular scopes still read administrators. The refusal is answered after the request’s 400 and 404, writes nothing, carries the insufficient_scope challenge of the scheme the token was sent with, such as WWW-Authenticate: Bearer realm="goiabada", error="insufficient_scope", error_description="...", scope="authserver:manage", and leaves an administrator_change_refused audit record.
Media typeapplication/json

Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.

object
error_code

Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.

string
error_description
required

A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.

string
error_field

A JSON Pointer (RFC 6901) to the member of the request body the refusal is about, such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand. Left out when the refusal names no member. It’s set by the refusals of a brand’s footer links, palette and custom CSS, and of an email template’s text and brandId.

string

Example generated

{
"error_code": "example",
"error_description": "example",
"error_field": "example"
}
WWW-Authenticate
string

An insufficient_scope challenge in the scheme the token was sent with, Bearer or DPoP, on every refusal but FORBIDDEN and ACCOUNT_DELETION_DISABLED, which omit it.

Resource not found

Media typeapplication/json

Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.

object
error_code

Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.

string
error_description
required

A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.

string
error_field

A JSON Pointer (RFC 6901) to the member of the request body the refusal is about, such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand. Left out when the refusal names no member. It’s set by the refusals of a brand’s footer links, palette and custom CSS, and of an email template’s text and brandId.

string

Example generated

{
"error_code": "example",
"error_description": "example",
"error_field": "example"
}

The request failed inside the server, most often a storage error. error_code is INTERNAL_SERVER_ERROR: no detail about the failure, only the request id an operator can find the log line by, and retrying is reasonable. Key rotation’s 500 also answers KEY_SET_INCOMPLETE, which names its cause and no retry clears.

Media typeapplication/json

Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.

object
error_code

Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.

string
error_description
required

A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.

string
error_field

A JSON Pointer (RFC 6901) to the member of the request body the refusal is about, such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand. Left out when the refusal names no member. It’s set by the refusals of a brand’s footer links, palette and custom CSS, and of an email template’s text and brandId.

string

Example generated

{
"error_code": "example",
"error_description": "example",
"error_field": "example"
}