Get the project's email providers
- Sandbox: available
- Staging: available
- Production: unknown
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
providerslistsbrevo,sendgrid,resendandsmtp, each withconfiguredandready.configuredistruewhen 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 withPOST.readyistruewhen the provider can send: it is configured and, for SendGrid and SMTP, the project has a sender address.fromis the sender address (theEMAIL_FROMsecret), ornull.- 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'bearerAuthorizationBearer <JWT>Which providers are set up and can send, and the sender address. Never a secret.
application/json- response
projectId*stringfrom*stringThe sender address, or null when none is set.
providers*array<>curl -X GET 'https://api.sandbox.ovok.com/v1/email/templates/provider'{ "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" }' ```