Customize the pages and emails
This guide makes the pages your users see, and the emails they get, look and read like your product.
Brand the pages
Section titled “Brand the pages”-
In the admin console, open Admin, General and set App name, up to 30 characters. It’s shown at the top of the sign-in pages and ends their titles, as in “Sign in – Acme”. It also signs every email, and it’s the name authenticator apps list your users’ accounts under.
-
Open Admin, Branding, and open the brand marked Default. Choose its Appearance and its Theme, add your logo, favicon, background image, font and corners if you like, and click Save.
-
To give one client a look of its own, click New brand and create one, then choose it under Brand on the client’s Settings tab. See Clients for the pages it draws.
-
Give each client a display name and a logo, so users see which app they’re signing in to. See Clients.
The sections below cover brands and themes, the brand kit, a custom palette, footer links and a support contact, custom CSS, and the emails’ look and words.
Brands and themes
Section titled “Brands and themes”A brand is a look the pages are drawn in: a name, an appearance, a theme and its kit. A client’s pages are drawn in the brand chosen for it. The pages of a client with none, and the pages that belong to no client, are drawn in the default brand. A new install has one brand, Default, on Automatic and Blueberry.
The appearance is Automatic, Light or Dark. Automatic draws the pages light or dark, as each visitor’s device prefers.
The theme is one of eight built-in themes: Blueberry, Blackberry, Avocado, Plum, Tangerine, Guava, Coconut and High contrast. Each has a light and a dark palette whose text and borders meet WCAG 2.2 AA contrast. High contrast’s text meets 7:1. Or choose Custom, after them, to draw the brand in a custom palette of your own colors.
To change the default, open a brand and click Make default.
The default brand can’t be deleted, so make another one the default first.
The Admin API manages the same brands, from GET /api/v1/admin/brands, and GET /api/v1/admin/brand-themes lists each built-in theme’s colors. PUT /api/v1/admin/brands/{id} replaces the whole brand, so a member you leave out is emptied. To change one thing, send back the brand that GET /api/v1/admin/brands/{id} answers, with that change.
Custom palettes
Section titled “Custom palettes”A custom palette draws a brand’s pages in colors you choose, light and dark.
-
Open the brand and choose Custom under Theme. The Colors section opens under the theme cards, holding the colors of the theme you had chosen, to start from.
-
Choose Basic or Advanced. In Basic, you set four colors for each mode: Background, Card, Text and Brand color. In Advanced, you set all 23.
-
Type each color as
#and six hexadecimal digits, such as#2456c4, or pick it in the color well beside its field. The preview draws it as you type. -
Read the list at the foot of the Colors section, and fix the pairs you can. See Contrast warnings.
-
Click Save.
In Basic, the other 19 colors are worked out from your four when you save. The status colors, for danger, positive, caution and note messages, are Blueberry’s. To choose your own, use Advanced.
Saving a brand on a built-in theme deletes its custom palette.
Advanced shows the colors in four groups, Page, Text, Brand and Status, with each one’s token name, which the Admin API uses:
| Color | Token |
|---|---|
| Background | canvas |
| Card | surface |
| Subtle background | subtle |
| Border | line |
| Strong border | line-strong |
| Text | ink |
| Muted text | ink-muted |
| Brand color | brand |
| Strong brand color | brand-strong |
| Text on brand color | on-brand |
| Soft brand background | brand-soft |
| Focus ring | focus |
| Danger color | danger |
| Strong danger color | danger-strong |
| Text on danger color | on-danger |
| Soft danger background | danger-soft |
| Danger text | danger-ink |
| Soft positive background | positive-soft |
| Positive text | positive-ink |
| Soft caution background | caution-soft |
| Caution text | caution-ink |
| Soft note background | note-soft |
| Note text | note-ink |
Contrast warnings
Section titled “Contrast warnings”Goiabada checks a brand’s colors against the pairs its pages draw text, boundaries and focus rings in: 35 pairs in each mode, such as muted text on the card or the focus ring on the background. Each pair has a minimum contrast ratio from WCAG 2.2 level AA:
- 4.5:1 for text, from 1.4.3 Contrast (Minimum).
- 3:1 for a boundary or a focus ring, from 1.4.11 Non-text Contrast.
Every built-in theme meets them. A pair below its minimum never stops a save.
Only the modes the brand’s appearance draws are checked: both under Automatic, the light colors alone under Light, and the dark ones alone under Dark.
Passing every pair doesn’t make your pages meet WCAG 2.2 AA. That’s a claim about whole pages, against every one of its criteria, and your logo and background image aren’t checked.
Custom palettes through the Admin API
Section titled “Custom palettes through the Admin API”A custom palette is the theme custom with a palette member, in POST /api/v1/admin/brands and PUT /api/v1/admin/brands/{id}. palette holds mode, basic or advanced, and light and dark, each a map from a color’s token to its value:
curl -X PUT https://auth.example.com/api/v1/admin/brands/3 \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme", "appearance": "auto", "theme": "custom", "corners": "rounded", "font": "system-ui", "backgroundFit": "cover", "palette": { "mode": "basic", "light": {"canvas": "#f3f6f4", "surface": "#ffffff", "ink": "#17211b", "brand": "#1e7a4c"}, "dark": {"canvas": "#0f1512", "surface": "#17201b", "ink": "#e4ece7", "brand": "#5cc58f"} } }'PUT /api/v1/admin/brands/{id} gives each member’s rules. A basic palette is worked out again from its four colors each time it’s saved.
The brand kit
Section titled “The brand kit”A brand’s kit puts your logo, favicon, background image, font and corners on its pages. Each is optional: a brand you haven’t changed is drawn in Goiabada’s own look.
The auth server’s pages and the admin console’s home and its other card pages are drawn with the whole kit, and its Account pages with all of it but the background image. The admin console’s admin pages take only its colors and logo, as the admin console’s client explains.
Logo and app name
Section titled “Logo and app name”Logo is drawn above the app name on the sign-in card, and before the app name in the admin console’s header and sidebar. Dark logo takes its place in dark mode. Without one, the logo is drawn in both modes.
Turn on Hide the app name for a logo that already shows the name. The logo then stands for the name, and screen readers announce it as the app name. Page titles keep the app name either way.
A client’s own logo still shows on its screens, below the brand’s.
Favicon
Section titled “Favicon”Favicon is the icon in the browser’s tab. A page whose brand has one links it in place of Goiabada’s icons and web manifest.
Background image
Section titled “Background image”Background image is drawn behind the sign-in card, over the theme’s background color. It’s drawn on card pages only: the auth server’s pages and the admin console’s home and card pages, not its Account pages. Choose how it fills the page:
- Cover fills the page and may crop the image.
- Contain shows the whole image, with the theme’s background color around it.
- Tile repeats the image at its own size.
The card stays opaque over the image, so its text is as readable as on a page without one.
Font is one of six system families: System UI, Humanist, Geometric, Serif, Neo-grotesque and Rounded. Each is a list of fonts your visitors’ devices already have, so nothing is downloaded and text looks a little different from one device to another. Apple devices draw Rounded rounded. Windows and Android have no rounded font installed and draw it as an ordinary sans.
To use your own typeface, upload it under Font file and choose Uploaded font. One file is used for every weight, so a variable font works as it should, and a static one gets the browser’s own bold. Add a Bold font file too, and the font file draws the weights up to 500 and the bold one the heavier ones. Text shows in System UI while the font loads, and for any character it lacks. Code and other monospace text keep their own font.
Choosing another family keeps the files, so you can switch back without uploading them again.
Corners
Section titled “Corners”Corners are Square, Rounded or Pill. Rounded is Goiabada’s own look. Pill rounds a button or a single-line field fully, and rounds the card and boxes of several lines only as far as their content stays clear of the curve.
What you can upload
Section titled “What you can upload”| Field | Type | Size | Largest file |
|---|---|---|---|
| Logo, Dark logo | PNG or JPEG | 10 to 512 pixels a side | 1 MiB |
| Favicon | PNG, square | 48 to 512 pixels a side | 1 MiB |
| Background image | PNG, JPEG or WebP | 10 to 3840 pixels a side | 2 MiB |
| Font file, Bold font file | WOFF2 | 2 MiB |
Animated images are refused, since a looping animation on or behind the sign-in card has no way to pause it. GIF and SVG are refused too.
A file no brand uses is deleted once it’s a day old, so save the brand the same day you upload it.
Every file you upload is public, whether a brand uses it or not: anyone can download it from /brand-assets/{id} on the auth server, and the ids are sequential. Don’t upload a file you aren’t ready to publish.
The kit through the Admin API
Section titled “The kit through the Admin API”The Admin API sets the kit in two steps.
-
Upload each file as a brand asset of its kind, in the multipart field
file, withPOST /api/v1/admin/brand-assets/logo,/favicon,/backgroundor/font. A dark logo is uploaded as a logo, and both font files as a font. The answer holds the asset’sid:Terminal window curl -X POST https://auth.example.com/api/v1/admin/brand-assets/logo \-H "Authorization: Bearer $TOKEN" \ -
Name the asset by its
idin a slot of the brand, withPOST /api/v1/admin/brandsorPUT /api/v1/admin/brands/{id}. The slots arelogo,darkLogo,favicon,background,regularFontandboldFont:Terminal window curl -X PUT https://auth.example.com/api/v1/admin/brands/3 \-H "Authorization: Bearer $TOKEN" \-H "Content-Type: application/json" \-d '{"name": "Acme","appearance": "auto","theme": "blueberry","corners": "rounded","font": "uploaded","backgroundFit": "cover","hideAppName": true,"logo": {"id": 42},"regularFont": {"id": 43}}'
Footer links and support contact
Section titled “Footer links and support contact”A brand can show up to three links under the card, such as your privacy policy, a status page or your company’s site, and a way for a stuck user to reach your support. Both are optional.
-
Open Admin, Branding, and open the brand.
-
Under Footer links, give Link 1 a Label and a URL, and fill in Link 2 and Link 3 if you want more.
-
Open Label in each language under a link to give it a label in each language your users read.
-
Under Support contact, fill in any of Email address, Support page URL and Phone number.
-
Click Save.
The footer is drawn under the card on every page of the auth server, and on the admin console’s home and its other card pages. On the console’s Account pages it follows the page’s content. The console’s admin pages draw no footer. It’s small text on the page’s background color, and on a brand with a background image it sits on a panel in the card’s color, so it stays readable whatever the image.
A brand shows only its own links and contact. A client whose brand has none shows no footer, even when the default brand’s has one.
Everything in the footer is public, as the pages that draw it are.
Footer links
Section titled “Footer links”The links are drawn in the order of their rows, and each one opens in a new tab, so a click during a sign-in leaves the sign-in page open.
- Label is required, up to 40 characters, without
<or>. - URL is required, up to 256 characters. It starts with
https:and names a site, with no user name or password in it. - Label in each language holds one optional label for each built-in language, with the same limits as Label.
A page shows each link’s label in the language the page is written in. Where the link has none for that language, it shows Label. Goiabada can’t tell a screen reader which language that label is in, so fill in a label for each language your users read.
Support contact
Section titled “Support contact”The footer’s contact line reads “Need help?”, followed by each value you set: the email address and the phone number as themselves, so they can be copied, and the URL as a link named “Support page”, which opens in a new tab.
- Email address is up to 254 characters, in the shape any account’s address takes.
- Support page URL follows the rule of a footer link’s URL.
- Phone number is a
+, the country code and the number, up to 15 digits in all, the first not 0. You can type it with spaces, hyphens, dots and parentheses, and they’re removed when you save, so the page shows the digits alone, such as+442079460958.
The footer through the Admin API
Section titled “The footer through the Admin API”A brand carries the footer in four members, in POST /api/v1/admin/brands, PUT /api/v1/admin/brands/{id} and every brand they answer: footerLinks, the links in the order they’re drawn, and supportEmail, supportUrl and supportPhone. A link is an object with url, label and, optionally, labels, a label for each language by its tag, such as "pt-BR":
curl -X PUT https://auth.example.com/api/v1/admin/brands/3 \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme", "appearance": "auto", "theme": "blueberry", "corners": "rounded", "font": "system-ui", "backgroundFit": "cover", "footerLinks": [ {"url": "https://acme.example/privacy", "label": "Privacy", "labels": {"pt-BR": "Privacidade", "de": "Datenschutz"}}, {"url": "https://status.acme.example", "label": "Status"} ], "supportEmail": "[email protected]", "supportUrl": "https://acme.example/help", "supportPhone": "+44 20 7946 0958" }'Custom CSS
Section titled “Custom CSS”A brand’s custom CSS restyles its pages beyond what its other choices do, such as a page’s layout, a heading’s size or a card’s border.
-
Open Admin, Branding, and open the brand.
-
Under Custom CSS, write your rules. Write them against the styling contract: its variables, page names and classes stay the same from one release to the next, so your rules keep matching after an upgrade.
-
Click Save.
-
Open a page in the brand to see your rules. If a page becomes unusable, safe mode draws it without your CSS.
body[data-page="sign-in"] .auth-card { border: 2px solid var(--color-brand);}The CSS goes after the brand’s own styles, so a rule of yours wins over a built-in one of the same specificity. It’s on every page of the auth server, and on the admin console’s Account pages, its home page, and its error and sign-out pages. It’s never on the console’s admin pages.
What custom CSS can hold
Section titled “What custom CSS can hold”Custom CSS can’t make a browser load anything, so it can’t send a visitor’s data anywhere:
- It’s up to 64 KB.
- It can’t hold
@import. - It can’t hold a URL, except a
data:image inurl(), such asurl("data:image/svg+xml,…"). Upload a background, a logo or a font in the brand’s kit instead.
Custom CSS through the Admin API
Section titled “Custom CSS through the Admin API”A brand carries its custom CSS as one string, customCss, in POST /api/v1/admin/brands, PUT /api/v1/admin/brands/{id} and every brand they answer:
curl -X PUT https://auth.example.com/api/v1/admin/brands/3 \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme", "appearance": "auto", "theme": "blueberry", "corners": "rounded", "font": "system-ui", "backgroundFit": "cover", "customCss": "body[data-page=\"sign-in\"] .auth-card {\n border: 2px solid var(--color-brand);\n}\n" }'An answer carries customCss as it was saved, with each line break turned into a line feed, or "" for a brand with none, blank CSS included.
Branded emails
Section titled “Branded emails”Every email the auth server sends is drawn in a brand, so a password reset looks like the sign-in it came from.
What an email takes from its brand
Section titled “What an email takes from its brand”An email is a card on the brand’s background color, with the brand’s Logo above the app name, as on the sign-in card. Hide the app name hides the name there too, and the logo then carries the app name as its alternative text, which a mail client that blocks images shows in its place. The card takes the brand’s colors, its Corners and its Font. An Uploaded font is drawn in System UI, since an email can’t load a font file.
The password reset link, the activation link, a new user’s setup email and the welcome email can each show a button in the brand’s color, where their body holds {{button}}, and every other link is in the brand’s color too. The brand’s footer links and support contact are drawn under the card. The background image, the favicon and the custom CSS never reach an email.
An email doesn’t follow the reader’s light or dark mode, since many mail clients ignore it. A brand whose Appearance is Dark is drawn in its dark colors, with its Dark logo if it has one. Light and Automatic brands are drawn in their light colors.
Some mail clients, Outlook among them, redraw a light email in dark colors when the reader uses dark mode. They leave the logo as it is, so a logo in dark ink on a transparent background can be hard to read there. Give it a background of its own, or a light outline, and it reads in both.
Every email is sent as plain text too, for mail clients that show no HTML: its text, its links written out, and the footer.
Which brand an email takes
Section titled “Which brand an email takes”Where an email is sent from decides its brand:
| Sent from | Drawn in | Emails |
|---|---|---|
| The pages of a sign-in to your app | The client’s brand | When someone registers, the activation link, the welcome email and the notice that the address already has an account. The password reset link, and the notice that the password was reset. The notices that two-factor authentication was set up, that a recovery code was used, and that the authenticator was disabled after too many wrong codes. |
| The Account pages, or the Account API | The brand of the client the access token was issued to, which for the admin console’s Account pages is the admin console’s own client’s brand | The verification code. The notices that the email address or the password was changed, that two-factor authentication was set up or turned off, that the recovery codes were replaced, that the account was deleted, and that the authenticator was disabled after too many wrong codes while confirming a deletion. |
| An administrator’s action | The default brand | A new user’s setup email. The notices that an administrator changed the password, turned off two-factor authentication or deleted the account. The test email from Send test email. |
A client with no brand of its own gives the default brand, as its pages do: see Clients. So does the forgot password page opened on its own, outside a sign-in, and a reset link opened in another browser or after the sign-in ended: the notice that the password was reset is then in the default brand too.
Safe mode
Section titled “Safe mode”Safe mode draws the pages without a brand’s custom CSS, in the built-in Blueberry colors in place of a custom palette, and in System UI in place of an uploaded font. Nothing saved changes. Use it to sign in and fix a brand whose pages you can’t read or use.
-
Open an admin console address with
?goiabada_safe_mode=trueat the end, such ashttps://admin.example.com/admin/settings/branding?goiabada_safe_mode=true. -
Sign in if you’re asked to. The admin console’s pages are now in safe mode, and its admin pages say so.
-
Fix the brand under Admin, Branding.
-
Sign out to leave safe mode, and check the pages.
You can also turn it on:
- For one sign-in to your app, with
goiabada_safe_mode=trueon the authorization request. Every page of that sign-in is drawn in safe mode. - For every page of both servers, for everyone, with
GOIABADA_AUTHSERVER_BRAND_SAFE_MODEset totrueon the auth server. It lasts until you unset it and restart the auth server, and signing out doesn’t end it.
How the language is chosen
Section titled “How the language is chosen”The pages come in English, Portuguese (Brazil), Spanish, French, Italian and German. On the auth server’s pages and in the admin console, the language is the first of these that names one:
- The user’s Page language, which they choose under Account, Profile in the admin console. An administrator can set it too, on the user’s Profile page.
- A
ui_localesparameter: one or more language tags in order of preference, separated by single spaces, such asui_locales=es pt-BR. On the auth server, it’s the authorization request’s or the sign-out’s. It’s kept for the rest of that sign-in, and applies to the error page the auth server shows when it refuses the request outright. In the admin console, it’s?ui_locales=in the page’s address. - The browser’s
Accept-Languageheader. - English.
A user on Automatic, where everyone starts, skips the first. So does a page drawn for nobody Goiabada knows yet, which is why your app’s ui_locales still matters:
- The admin console uses the page language once the user has signed in to it.
- The auth server uses it once the user has entered their password: on the one-time code, recovery code and consent pages, on signing out, and on every page shown to a browser that’s signed in.
- A browser that isn’t signed in gets the sign-in, forgot password, registration and activation pages in the language of the other sources, since the auth server doesn’t know who’s there. The email address typed on the sign-in page never picks the language, so the page can’t reveal an account’s language to whoever types it.
- The password reset page, opened from the email, is in the page language of the user the link is for.
The auth server reads the page language each time it draws a page, so a change shows on its next page. The admin console reads it when the user signs in to it. A change they save there shows on their next page, and one made elsewhere, such as by an administrator, reaches them when they next sign in or open their profile.
For ui_locales and Accept-Language, the first of their languages Goiabada has text for wins, or English when it has none of them: ui_locales=sv fr shows French, and ui_locales=sv alone shows English. A regional tag reads its language, so fr-CA shows French.
An email to a user is written in their page language. On Automatic, it’s the Language and region on their profile, or English when they haven’t picked one. A regional language reads its language’s email, so fr-CA gets the French one, and a language with no built-in emails gets the English one. The activation link and the welcome email a user gets when they register are written in the language of the page they registered on, since their account has no language yet.
Email templates
Section titled “Email templates”An email template is what one of the auth server’s 19 emails says: its subject, its body and, for the four with a button, the button’s label. Each comes in the six built-in languages, and you can reword any of them in the admin console. How an email looks is its brand’s: see Branded emails.
-
Open Admin, Email, and the Email templates tab. The list shows every email, when it’s sent, and which languages you’ve edited.
-
Open an email. It opens in the language you read the admin console in, or in English. Choose another language above the form.
-
Edit Subject, Button label and Body. The body must hold the placeholders marked required.
-
Check the Preview beside the form. Choose a Brand to see it in another one.
-
To see it in a mail client, type an address under Send test email and send it.
-
Click Save. The next email sent in that language uses it.
Each language is saved, and reset with Reset to default, on its own.
Only the fields you change are kept. A field you leave as it was follows the built-in text when you upgrade, so a release that rewords a body still reaches your users when you’ve changed only the subject.
An edit applies to every brand and every client.
The body’s format
Section titled “The body’s format”The body is written in a small set of Markdown:
- A blank line starts a paragraph, and a single line break is kept.
**bold**and*italic*.[link text](https://example.com), drawn in the brand’s color. A link leads to anhttps:,http:,mailto:ortel:address. Any other, such asjavascript:, keeps its text and loses its address.- Lines starting with
-for a bulleted list, or1.for a numbered one.
Anything else, such as a heading, a quote, a table, code or HTML, is shown as you typed it, and no image is loaded.
The subject is up to 200 characters, on one line, the button label up to 60 characters, and the body up to 20,000 characters. None of them can be empty. The subject and the button label are plain text, and the button label takes no placeholders.
Placeholders
Section titled “Placeholders”A placeholder is a name between double braces, such as {{name}}, and the email writes its value there. {{ name }}, with spaces, reads the same. To write two braces, type \{{. A value is always written as text, so a name that looks like Markdown or HTML shows as it is.
| Placeholder | What it writes |
|---|---|
{{app_name}} |
The App name under Admin, General. |
{{name}} |
The user’s full name, or the address the email is sent to when they have none. |
{{link}} |
The email’s link. On its own, the address drawn as a link to itself. As the whole address of a link, [Reset your password]({{link}}), that link. |
{{button}} |
The brand’s button to the link, with the Button label on it. It goes on a line of its own. |
{{code}} |
The verification code. Alone in its paragraph, it’s drawn in a box. In a sentence or the subject, it’s the code as text. |
{{expiry}} |
How long the link or the code lasts, in the email’s language, such as “5 minutes”. |
{{codes_left}} |
How many unused recovery codes are left, as a number. |
Each email’s placeholders
Section titled “Each email’s placeholders”| Identifier | Placeholders | Required | |
|---|---|---|---|
| Password reset link | password_reset_link |
{{app_name}}, {{name}}, {{link}}, {{button}}, {{expiry}} |
{{link}} |
| Activation link | activation_link |
{{app_name}}, {{link}}, {{button}}, {{expiry}} |
{{link}} |
| Welcome | welcome |
{{app_name}}, {{link}}, {{button}} |
None |
| Address already has an account | registration_existing_account |
{{app_name}}, {{link}} |
None |
| New user’s setup | new_user_setup |
{{app_name}}, {{name}}, {{link}}, {{button}}, {{expiry}} |
{{link}} |
| Verification code | verification_code |
{{app_name}}, {{name}}, {{code}}, {{link}}, {{expiry}} |
{{code}} |
| Test email | test |
{{app_name}} |
None |
| Email address changed | email_address_changed |
{{app_name}}, {{name}} |
None |
| Password changed | password_changed |
{{app_name}}, {{name}} |
None |
| Password changed by an administrator | password_changed_by_administrator |
{{app_name}}, {{name}} |
None |
| Password reset | password_reset |
{{app_name}}, {{name}} |
None |
| Two-factor authentication set up | otp_enabled |
{{app_name}}, {{name}} |
None |
| Two-factor authentication turned off | otp_disabled |
{{app_name}}, {{name}} |
None |
| Two-factor authentication turned off by an administrator | otp_disabled_by_administrator |
{{app_name}}, {{name}} |
None |
| Authenticator disabled | otp_lockout |
{{app_name}}, {{name}} |
None |
| Recovery code used | recovery_code_used |
{{app_name}}, {{name}}, {{codes_left}} |
None |
| Recovery codes replaced | recovery_codes_replaced |
{{app_name}}, {{name}} |
None |
| Account deleted | account_deleted |
{{app_name}}, {{name}} |
None |
| Account deleted by an administrator | account_deleted_by_administrator |
{{app_name}}, {{name}} |
None |
Email templates through the Admin API
Section titled “Email templates through the Admin API”| Operation | Route | Scope |
|---|---|---|
| List every email, with each language’s status | GET /api/v1/admin/email-templates |
authserver:admin-read, authserver:manage-settings or authserver:manage |
| Read one email: its placeholders and, for each language, its built-in text, the editor’s text and its status | GET /api/v1/admin/email-templates/{email} |
authserver:admin-read, authserver:manage-settings or authserver:manage |
| Save one language | PUT /api/v1/admin/email-templates/{email}/{language} |
authserver:manage |
| Reset one language | DELETE /api/v1/admin/email-templates/{email}/{language} |
authserver:manage |
| Preview a text, saved or not, with sample values | POST /api/v1/admin/email-templates/{email}/{language}/preview |
authserver:admin-read, authserver:manage-settings or authserver:manage |
| Send a test of a text, saved or not | POST /api/v1/admin/email-templates/{email}/{language}/send-test |
authserver:manage |
{email} is the email’s identifier, and {language} one of en, de, es, fr, it and pt-BR.
A save sends the whole text of the language, with buttonLabel only for an email with a button:
curl -X PUT https://auth.example.com/api/v1/admin/email-templates/password_reset_link/en \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "subject": "Reset your {{app_name}} password", "buttonLabel": "Choose a new password", "body": "Hello {{name}},\n\n{{button}}\n\n{{link}}\n\nThe link expires in {{expiry}}." }'Each language has a status: default with no edit, edited when its edit is sent, and invalid when its edit breaks a rule and the built-in text is sent instead, with the problems listed. Saves, resets and test sends leave entries in the audit log.