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>'| Method | Path | Does |
|---|---|---|
GET | /v1/email/templates/provider | Lists the four providers and whether each can send. |
POST | /v1/email/templates/provider | Sets up a provider that is not set up yet. |
PATCH | /v1/email/templates/provider | Replaces 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.
| Field | Type | Description |
|---|---|---|
provider | string, required | brevo, sendgrid, resend or smtp. |
secret | string, required | The provider's credential, 1 to 2,000 characters. See the table below. |
from | string | The sender address, a valid email of up to 254 characters. One address serves the whole project. |
| Provider | secret | Needs from |
|---|---|---|
brevo | An API key that starts with xkeysib-. | No |
sendgrid | An API key that starts with SG.. | Yes |
resend | An API key that starts with re_. | No |
smtp | A 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.
| Field | Meaning |
|---|---|
from | The sender address, or null when none is set. |
providers[].configured | The project holds a secret for the provider that this server can read. |
providers[].ready | The 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.
| Status | Code | Cause |
|---|---|---|
400 | none | The token carries no project. |
401 | none | The bearer token is missing or invalid. |
403 | none | The caller is not a project admin. |
404 | PROVIDER_NOT_CONFIGURED | PATCH for a provider that is not set up. Set it up with POST. |
409 | PROVIDER_CONFIGURED | POST for a provider that is already set up. Use PATCH. |
409 | none | The project changed while Ovok wrote. Read it again and retry. |
422 | INVALID_SECRET | The secret is not one the provider takes. |
422 | FROM_REQUIRED | POST for SendGrid or SMTP when the project has no sender address and the body has no from. |
422 | none | The body fails validation, for example an unknown field or a PATCH with neither secret nor from. |
503 | ENCRYPTION_UNAVAILABLE | The server cannot encrypt secrets, so nothing is stored. |
Related
Last updated on