Configure an email provider

Store a provider's credential and the sender address for your project with /v1/email/templates/provider, and check that it is ready to send.

A template mapping sends only when its provider is ready. Three routes set that up for your current project: read which providers can send, set one up, and change one. Every route needs a project admin token, reading included, because the answer names the providers your project uses.

export OVOK_TOKEN='<access token of a project admin>'
MethodPathDoes
GET/v1/email/templates/providerLists the four providers and whether each can send.
POST/v1/email/templates/providerSets up a provider that is not set up yet.
PATCH/v1/email/templates/providerReplaces the secret or the sender address of a provider that is set up.

Ovok stores each value encrypted with a key of your project's own. It never returns a secret.

Set up a provider

The body has the provider, its credential, and the sender address.

FieldTypeDescription
providerstring, requiredbrevo, sendgrid, resend or smtp.
secretstring, requiredThe provider's credential, 1 to 2,000 characters. See the table below.
fromstringThe sender address, a valid email of up to 254 characters. One address serves the whole project.
ProvidersecretNeeds from
brevoAn API key that starts with xkeysib-.No
sendgridAn API key that starts with SG..Yes
resendAn API key that starts with re_.No
smtpA URL, smtp://user:password@host:port or smtps://…, whose host resolves to a public address.Yes
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/email/templates/provider' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"provider":"brevo","secret":"{{BREVO_API_KEY}}","from":"care@example.com"}'

The answer is 201 with the project's providers:

{
  "projectId": "{{PROJECT_ID}}",
  "from": "care@example.com",
  "providers": [
    { "provider": "brevo", "configured": true, "ready": true },
    { "provider": "sendgrid", "configured": false, "ready": false },
    { "provider": "resend", "configured": false, "ready": false },
    { "provider": "smtp", "configured": false, "ready": false }
  ]
}

Ovok checks only the shape of the secret. It does not try the key at your provider, so confirm that it works by sending a test email.

from is one address for the whole project: sending it changes the sender for every provider, Brevo and Resend included.

Check which providers can send

curl --get 'https://api.sandbox.ovok.com/v1/email/templates/provider' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

The answer has the shape shown above.

FieldMeaning
fromThe sender address, or null when none is set.
providers[].configuredThe project holds a secret for the provider that this server can read.
providers[].readyThe provider can send: it is configured and, for SendGrid and SMTP, the project has a sender address.

A secret stored with another key reads as not configured. Set it up again with POST, which replaces it.

These are your project's own secrets. A message sent through a parent project's or the platform's mapping uses that project's secrets, not these.

Change a provider

Send the provider and at least one of secret and from. The rules for the values are those of POST.

curl --request PATCH \
  --url 'https://api.sandbox.ovok.com/v1/email/templates/provider' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"provider":"brevo","from":"hello@example.com"}'

The answer is 200 with the project's providers. You can replace from but not clear it.

Errors

Branch on the code of the body, not on its text.

StatusCodeCause
400noneThe token carries no project.
401noneThe bearer token is missing or invalid.
403noneThe caller is not a project admin.
404PROVIDER_NOT_CONFIGUREDPATCH for a provider that is not set up. Set it up with POST.
409PROVIDER_CONFIGUREDPOST for a provider that is already set up. Use PATCH.
409noneThe project changed while Ovok wrote. Read it again and retry.
422INVALID_SECRETThe secret is not one the provider takes.
422FROM_REQUIREDPOST for SendGrid or SMTP when the project has no sender address and the body has no from.
422noneThe body fails validation, for example an unknown field or a PATCH with neither secret nor from.
503ENCRYPTION_UNAVAILABLEThe server cannot encrypt secrets, so nothing is stored.

Last updated on

On this page