OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Email

Set up an email provider

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

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

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

Authorization

bearer
headerAuthorizationBearer <JWT>

Request Body

application/json
  1. body
provider*string
Value in"brevo""sendgrid""resend""smtp"
secret*string

The API key, or the smtp(s):// URL for SMTP. Never returned.

Length1 <= length <= 2000
from?string

The sender address, the EMAIL_FROM secret.

Formatemail
Lengthlength <= 254
Defaultnull

Response Body

The providers after the change.

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

The sender address, or null when none is set.

providers*array<>
Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/email/templates/provider' \  -H 'Content-Type: application/json' \  -d '{  "provider": "brevo",  "secret": "string"}'
Example Response
{  "projectId": "string",  "from": "string",  "providers": [    {      "provider": "brevo",      "configured": true,      "ready": true    }  ]}

Get the project's email providers GET

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 ```bash curl -X GET 'https://api.sandbox.ovok.com/v1/email/templates/provider' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Change an email provider PATCH

Changes an email provider your current project has set up: replaces its secret, the sender address, or both. Each value is stored encrypted 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` names the provider to change. One that is not set up returns 404 `PROVIDER_NOT_CONFIGURED`: set it up with `POST /v1/email/templates/provider`. - Send `secret`, `from`, or both. The rules are those of `POST`; a secret the provider does not take returns 422 `INVALID_SECRET`. - `from` is one sender address for the whole project, so changing it changes it for every provider. It cannot be cleared, only replaced. - When the server has no encryption key, nothing is stored and the answer is 503 `ENCRYPTION_UNAVAILABLE`. - A 409 means the project changed while the server wrote. Read it again and retry. - The answer has the project's providers as `GET /v1/email/templates/provider` returns them. ## Example ```bash curl -X PATCH '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-…" }' ```