Map templates with the API
List, read, create, replace and remove email template mappings with /v1/projects/me/email-templates, with every error and the cases that surprise people.
Four routes manage the mappings of your current project: which template of your provider each Ovok message sends, per language and domain. Nothing is sent without a mapping, so map the templates before you turn on the flows that send them (Invitations). The routes store mappings only; ready tells you whether the provider's secrets are in place.
| Method | Path | Who |
|---|---|---|
GET | /v1/projects/me/email-templates | Any practitioner |
GET | /v1/projects/me/email-templates/:name | Any practitioner |
PUT | /v1/projects/me/email-templates/:name | A project admin |
DELETE | /v1/projects/me/email-templates/:name | A project admin |
:name is one of the template names. An unknown name answers 400 with code UNKNOWN_TEMPLATE and the list in acceptedNames.
Which mapping: language and domain
GET :name, PUT and DELETE identify a mapping by its template and its context, given in the query:
| Query | Description |
|---|---|
language | One of Ovok's locale codes, such as en-US or de-DE. A bare en is stored as en-US. Any other value answers 422, because a mail's language is always one of those. |
domain | A host name such as app.example.com, lower-cased, without scheme or port. |
Leave one out for a mapping that names none. They are matched exactly: ?language=en-US is not the same mapping as no context. Unknown query keys answer 422, so a typo such as ?langauge= can never write the project-wide mapping.
List
curl --get 'https://api.sandbox.ovok.com/v1/projects/me/email-templates' \
--header "Authorization: Bearer ${OVOK_TOKEN}"The response includes the project's own mappings and the template names without a project mapping:
| Field | Example | Meaning |
|---|---|---|
projectId | 5b1f0c0e-… | Project whose mappings were read. |
mappings[].name | INVITE_TO_PROJECT | Ovok message name. |
mappings[].provider | brevo | Provider for this mapping. |
mappings[].templateId | 12 | Template id at the provider. |
mappings[].language | en-US | Language context, or null when none was set. |
mappings[].domain | null | Domain context, or null when none was set. |
mappings[].subject | null | SMTP subject; null for other providers. |
mappings[].ready | true | False when a required provider secret or EMAIL_FROM is missing. Presence only is checked, not whether the credential works. |
unmapped[] | RESET_PASSWORD, PATIENT_WELCOME | Names without a mapping in this project, in any language or domain. A parent or platform mapping may still apply, and an unmapped patient variant may use its shared template. |
Inherited mappings are not listed, and SMTP html is omitted. A mapping stored with a language or host these routes refuse can be listed but not addressed; recreate it with a language and domain written as above.
A mapping can be shadowed: Ovok tries the most specific context first, and within a level your project, then your parent, then the platform. A parent's or the platform's mapping at a more specific level beats yours at a less specific one, so ready: true does not promise yours is the one that goes out. See how Ovok picks a mapping.
Read one
curl --get 'https://api.sandbox.ovok.com/v1/projects/me/email-templates/INVITE_TO_PROJECT' \
--header "Authorization: Bearer ${OVOK_TOKEN}" \
--data-urlencode 'language=en-US'The answer is the mapping with an html field, null unless the provider is SMTP. Any practitioner can read it, SMTP HTML included. 404 when the template is not mapped for that language and domain, even if a parent project or the platform maps it.
Create or replace
curl --request PUT \
--url 'https://api.sandbox.ovok.com/v1/projects/me/email-templates/INVITE_TO_PROJECT?language=en-US' \
--header "Authorization: Bearer ${OVOK_TOKEN}" \
--header 'Content-Type: application/json' \
--data '{"provider":"brevo","templateId":"12"}'| Body field | Required | Description |
|---|---|---|
provider | Yes | brevo, sendgrid, resend or smtp. |
templateId | Yes | Your template's id at the provider, up to 200 characters: digits for Brevo, d- and lower-case hex for SendGrid, no whitespace for Resend and SMTP. |
subject | SMTP only | Up to 998 characters. |
html | SMTP only | Up to 200,000 characters. |
Other fields are refused: language and domain belong in the query. The answer is 200 with the mapping as stored, whether created or replaced. Ovok test-renders SMTP content with the template's example parameters, so a typo answers 422 now instead of failing every send later. One context uses one provider: to switch, remove that context's mappings first.
Remove
curl --request DELETE \
--url 'https://api.sandbox.ovok.com/v1/projects/me/email-templates/INVITE_TO_PROJECT?language=en-US' \
--header "Authorization: Bearer ${OVOK_TOKEN}"The answer is 204 with no body. Removing the last mapping of a context removes its ConceptMap, which can bring back an older one for the same language and domain.
What can go wrong
| Status | code or message | Cause |
|---|---|---|
400 | UNKNOWN_TEMPLATE | :name is not a template name. The body lists acceptedNames. |
401 | The token is missing or invalid. | |
403 | The caller is not a practitioner, or for PUT and DELETE not a project admin. | |
404 | <name> is not mapped for language … and domain …. | GET :name or DELETE of a mapping the project does not have. (none) means that part was left out. |
409 | PROVIDER_MISMATCH | That language and domain already use another provider. Remove its mappings first, or map with that provider. |
409 | Resource is locked by another write (locked) | Another write to the project's mappings is running. Retry; writes are not queued, so send parallel PUTs in turn. |
409 | The mappings changed while the server wrote, or the write waited too long. Read them again and retry. | |
422 | INVALID_TEMPLATE_ID | templateId is not valid for the provider. |
422 | INVALID_TEMPLATE_CONTENT | SMTP without a subject or html, a blank html, subject or html for another provider, or SMTP content that does not render with the message's parameters. |
422 | A list of path and message | A field or query value is missing, invalid, or not recognised. |
500 | The mapping could not be saved in this project. |
Related
Last updated on