# Email templates

Canonical page: https://docs.ovok.com/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.

```mermaid
flowchart LR
  event[Something happens: an invitation, a reset, a sign-up] --> name[Ovok template name]
  name --> map[Your mapping, by language and domain]
  map --> tpl[Your provider template]
  tpl --> mail[Email sent]
```

**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 [#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 [#what-you-need]

1. **A template at your provider** (or, for SMTP, a subject and HTML) written with the [parameters of the Ovok message](/email-templates/template-catalogue).
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 [#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 [#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](/email-templates/template-catalogue#patient-variants).

## Settings and features that affect email [#settings-and-features-that-affect-email]

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

The flows that use them are in [Authentication](/authentication) and [Invitations](/invitations).

## Next [#next]

1. [Set up email sending](/email-templates/set-up-email)
2. [Template catalogue and parameters](/email-templates/template-catalogue)
3. [Map templates with the API](/email-templates/map-templates)
4. [Troubleshooting](/email-templates/troubleshooting)
