# Map an email template

Canonical page: https://docs.ovok.com/api/email/map-an-email-template

`PUT /v1/projects/me/email-templates/{name}`

Maps an Ovok email template to a template of your email provider, for one language and domain. It replaces what the template was mapped to there, or adds the mapping when there is none.

**Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy.
**Scope:** the caller's project (from the token).

## Behaviour

- `:name` must be one of the template names. An unknown one returns 400 `UNKNOWN_TEMPLATE` with the accepted names.
- `language` and `domain` in the query say where the mapping applies; leave one out for none. `language` is one of Ovok's locale codes, such as `en-US` or `de-DE`, because that is what a mail's language is matched on; a bare `en` is stored as `en-US`, and any other value returns 422. `domain` is a host name, lower-cased, without scheme or port. See `GET /v1/projects/me/email-templates` for how sending picks between mappings.
- `provider` is `brevo`, `sendgrid`, `resend` or `smtp`. `templateId` is up to 200 characters and must be valid for the provider: digits only for Brevo, `d-` followed by lower-case hex for SendGrid, and no whitespace for Resend and SMTP. Otherwise 422 `INVALID_TEMPLATE_ID`.
- SMTP has no hosted templates: send the `subject` (up to 998 characters) and the `html` (up to 200,000 characters) with it, and nothing else may carry them. A missing or blank one for SMTP, or either for another provider, returns 422 `INVALID_TEMPLATE_CONTENT`.
- An SMTP subject and html are test-rendered with the template's example params before they are stored, the way sending renders them: a param the template does not have, or a block that is not closed, returns 422 `INVALID_TEMPLATE_CONTENT`. `GET /v1/email/templates` lists every template's params and how each provider writes a param.
- One language and domain use one provider. Mapping with another one than the one already there returns 409 `PROVIDER_MISMATCH`: remove that language and domain's mappings first.
- This does not set up the provider. Its credential and `EMAIL_FROM` are project secrets; until they exist the mapping is stored with `ready: false` and nothing is sent through it.
- Writes to a project's mappings are one at a time. A second write that arrives while another is running is refused with 409 and not queued: retry it. A 409 also means the mappings changed while the server wrote; read them again and retry.

## Example

```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/projects/me/email-templates/INVITE_TO_PROJECT?language=en-US' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
  -H 'Content-Type: application/json' \
  -d '{ "provider": "brevo", "templateId": "12" }'
```