Email

Get the project's email providers

  • Sandbox: available
  • Staging: available
  • Production: unknown
GET
/v1/email/templates/provider

Returns which email providers your current project has set up, whether each can send, and the sender address. It never returns a secret.

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

  • providers lists brevo, sendgrid, resend and smtp, each with configured and ready.
  • configured is true when the project holds a secret for the provider that this server can read: its API key, or the SMTP URL. A secret stored with another key reads as not configured; set it up again with POST.
  • ready is true when the provider can send: it is configured and, for SendGrid and SMTP, the project has a sender address.
  • from is the sender address (the EMAIL_FROM secret), or null.
  • These are the caller's project's own secrets. A mail sent through a parent project's or the platform's template mapping uses that project's secrets, not these.
  • The project's email template mappings (GET /v1/projects/me/email-templates) say which provider each mail is sent through. A mapping sends only when its provider is ready.

Example

curl -X GET 'https://api.sandbox.ovok.com/v1/email/templates/provider' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Response Body

Which providers are set up and can send, and the sender address. Never a secret.

application/json
  1. response
projectId*string
from*string

The sender address, or null when none is set.

providers*array<>
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/email/templates/provider'
Example Response
{  "projectId": "string",  "from": "string",  "providers": [    {      "provider": "brevo",      "configured": true,      "ready": true    }  ]}

Map an email template PUT

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" }' ```

Set up an email provider POST

Sets up an email provider for your current project: stores its secret and, optionally, the sender address. Each value is stored encrypted with a key of the project's own and is never returned. **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 - `provider` is `brevo`, `sendgrid`, `resend` or `smtp`. - `secret` is the provider's credential, up to 2,000 characters: - Brevo: an API key starting with `xkeysib-`. - SendGrid: an API key starting with `SG.`. - Resend: an API key starting with `re_`. - SMTP: a URL `smtp://user:password@host:port` or `smtps://…`, whose host resolves to a public address. Anything else returns 422 `INVALID_SECRET`. The key is not tried against the provider. - `from` is the sender address, one for the whole project. SendGrid and SMTP need it: setting one up when the project has none and `from` is not sent returns 422 `FROM_REQUIRED`. Brevo and Resend send from the template's own sender when there is none. Sending `from` sets it for the whole project, so Resend then sends from it too. - A provider whose secret this server cannot read (stored with another key) counts as not set up, so `POST` replaces it. - A provider that is already set up returns 409 `PROVIDER_CONFIGURED`: change it with `PATCH /v1/email/templates/provider`. - When the server has no encryption key, nothing is stored and the answer is 503 `ENCRYPTION_UNAVAILABLE`. - A 409 without a code means the project changed while the server wrote. Read it again and retry. - The answer is 201, with the project's providers as `GET /v1/email/templates/provider` returns them. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/email/templates/provider' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "provider": "brevo", "secret": "xkeysib-…", "from": "care@example.com" }' ```