Email templates

Ovok sends emails on your project's behalf: invitations, password resets, welcome messages and more. Each message is rendered from your template, hosted by your email provider or, for SMTP, stored with the mapping. Template mapping tells Ovok which of your templates each Ovok message uses.

Nothing is sent without a mapping. If no mapping applies to a message, Ovok skips the email, and for invitations it then undoes the invitation. Set the mappings before you turn on the flows that send them.

Providers

Provider	Where the template lives	Template id	Credential secret	Needs EMAIL_FROM
Brevo	In Brevo	Digits, such as 12	BREVO_API_KEY	No
SendGrid	In SendGrid, as a dynamic template	d- and lower-case hex	SENDGRID_API_KEY	Yes
Resend	In Resend	Any text without spaces	RESEND_API_KEY	No
SMTP	In the mapping: a subject and HTML you send with it	Any text without spaces	SMTP_URL	Yes

What you need

1. A template at your provider (or, for SMTP, a subject and HTML) written with the parameters of the Ovok message.
2. The provider's credential and, where needed, EMAIL_FROM, stored as project secrets. The mapping routes report whether they are present as ready.
3. A mapping from the Ovok template name to your template, created with the API.

The routes

All four are under /v1/projects/me/email-templates. Any practitioner can read; only a project admin can write.

Method	Path	What it does
GET	/v1/projects/me/email-templates	List the project's mappings and the names it has none for.
GET	/v1/projects/me/email-templates/:name	Read one mapping, with its HTML for SMTP.
PUT	/v1/projects/me/email-templates/:name	Create or replace a mapping.
DELETE	/v1/projects/me/email-templates/:name	Remove a mapping.

How Ovok picks a mapping

A mapping can name a language (such as en-US) and a domain (the site your user is on, such as app.example.com). When a message goes out, Ovok tries the most specific context first and moves down:

1. domain and language
2. domain and the project's default language
3. domain alone
4. language alone
5. the project's default language
6. no language and no domain

Within one level it uses your project's mapping, then your parent project's, then the platform's. A parent's or the platform's mapping at a more specific level is therefore used before your own at a less specific one. Patient variants of four templates fall back to the shared template when a mapping does not map them: see the catalogue.

Settings and features that affect email

Setting or feature	What it does for email
PATIENT_APP_URL and PRACTITIONER_APP_URL	Where the links in your emails point, and the baseUrl of every message.
PATIENT_INVITATION_ENABLED and PRACTITIONER_INVITATION_ENABLED	Whether the invitations that send emails can run at all.
PATIENT_REGISTRATION_ENABLED	Whether patients can register, which sends the welcome email.
CLINICIAN_INVITE_ON_BUSINESS_EMAIL	Turns a work-email registration into an invitation email.
Patient sharing	practitionerSharingEnabled switches on the four share and patient invitation emails.
email feature	Email sent by your automations (Bots). It does not control these templates.
MAILING_ENABLED	Reserved. It controls no email.

The flows that use them are in Authentication and Invitations.

Next

1. Set up email sending
2. Template catalogue and parameters
3. Map templates with the API
4. Troubleshooting