Email templates

You can replace the built-in auth emails with your own HTML. Each project has three template types. Any type you have not customized uses a built-in default design, colored with your brand color and headed with your logo.

Template types

These are the only types. Saving any other type returns 400 Invalid template type. See Email & SMTP for the exact trigger of each email.

Variables

How variables are rendered:

• Variables work in the subject, the HTML body and the plain-text body.
• Write them without spaces: {{otp}} works, {{ otp }} is left as-is.
• Unknown variables, and variables a type does not support, become an empty string.
• In the HTML body, every value is HTML-escaped except {{header_html}}, which is ready-made markup. A user name such as <b>Ada</b> arrives as text, not markup.
• The subject and the plain-text body are plain text, so values are inserted unescaped.

{{app_name}} — Your verification code

Built-in defaults

If a type has no custom template, OrbitNest renders its built-in design. This is the same layout as the Elegant starter in Studio, with your logo or project name as the header and colors derived from your brand color. The default subjects are:

The verification and reset defaults include a plain-text part. The welcome default is HTML only.

Edit templates in Studio

Open your project and go to Settings → Email Templates. Only workspace admins can save or reset templates, change the brand color, and send previews.

1. Pick a type: OTP Verification, Password Reset or Welcome Email. Types with a saved custom template are marked.
2. Edit the Subject. Click a variable chip to copy it, for example {{otp}}.
3. Choose a starter: Elegant, Vibrant or Corporate. Custom is selected automatically once you edit the HTML.
4. Edit in Visual (WYSIWYG), HTML (raw source) or Preview (rendered in the page) mode.
5. Click Save template.

If a type has no saved template, the editor opens with the Elegant starter already filled in. Nothing is stored until you click Save template. Until then, the server keeps sending the built-in default.

Logo and brand color

• Logo: upload it in Settings → General → Logo (PNG or SVG, up to 200 KB). Uploaded logos are attached to each auth email as an inline image and referenced with cid:, because Gmail and other clients block data: image URLs. {{header_html}} and {{logo_url}} handle this for you.
• Brand color: set Brand Color in the template editor and click Save color. It must be a 6-digit hex value such as #b8754a, which is also the default. It colors the built-in defaults and the starters.

Preview and test

• Preview mode shows the HTML in a sandboxed frame inside Studio. Variables are not replaced in this view.
• To send a real test, enter an address next to the Preview button at the bottom of the editor and click it. The current, unsaved subject and HTML are sent through your project's SMTP with the same escaping as real sends and these values:

A test send needs your own SMTP settings. The shared sender never sends previews.

• No SMTP configured: 400 with a message asking you to add SMTP settings.
• The SMTP server rejects the email: 502. Use Test in the SMTP settings to find out why.
• Test sends are limited to 10 per minute per IP address.

Reset to default

Reset to default appears when a type has a saved custom template. It deletes the template, and the project goes back to the built-in default for that type.

Templates API

These endpoints use a Studio admin access token, which is the access_token returned by POST /api/auth/signin. :projectId can be the project UUID or its slug. Any workspace member can read. Writes and previews need the admin role, and developers get 403.

Responses are wrapped as { "success": true, "data": ... }, except preview, which returns { "success": true, "message": "Preview sent to …" }. For preview, email must be a valid address (400 otherwise). If you leave out html_body and the type has no saved template, preview returns 200 with { "success": false, "message": "No template found" }.

curl -X PUT "https://api.orbitnest.io/api/projects/my-app/email-templates/otp_verification" \
  -H "Authorization: Bearer $ORBITNEST_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "{{app_name}} — Your verification code",
    "html_body": "{{header_html}}<p>Your code is <strong>{{otp}}</strong>. It expires in 10 minutes.</p>",
    "text_body": "Your {{app_name}} code is {{otp}}. It expires in 10 minutes."
  }'

{
  "success": true,
  "data": {
    "id": "6f1c…",
    "project_id": "…",
    "type": "otp_verification",
    "name": "OTP Verification",
    "subject": "{{app_name}} — Your verification code",
    "html_body": "{{header_html}}<p>Your code is …</p>",
    "text_body": "Your {{app_name}} code is {{otp}}. It expires in 10 minutes.",
    "is_active": true,
    "created_at": "…",
    "updated_at": "…"
  }
}

Send a test of the saved template:

curl -X POST "https://api.orbitnest.io/api/projects/my-app/email-templates/otp_verification/preview" \
  -H "Authorization: Bearer $ORBITNEST_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com" }'

PUT replaces the whole template. If you leave out text_body, any stored plain-text body is cleared.