Set up email sending

This page takes you from a project that sends no email to one that sends a mapped template. Changing mappings needs a project admin token; reading needs any practitioner.

export OVOK_TOKEN='<access token of a project admin>'

1. Create the template at your provider

Write the template with the parameters of the Ovok message you are replacing. The catalogue lists every message, its parameters, and how each provider writes one. For SMTP there is no hosted template: you send the subject and HTML in step 3.

2. Make sure the provider is configured

The provider's credential and, for SendGrid and SMTP, EMAIL_FROM are project secrets, not values you send with a mapping. The mapping routes do not store them. They report whether they are present, as ready, in step 4.

Provider	Secret	Also needs `EMAIL_FROM`
Brevo	`BREVO_API_KEY`	No
SendGrid	`SENDGRID_API_KEY`	Yes
Resend	`RESEND_API_KEY`	No
SMTP	`SMTP_URL`	Yes

3. Map the template

Send the Ovok template name in the path and your template in the body.

Brevo

curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/projects/me/email-templates/INVITE_TO_PROJECT' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"provider":"brevo","templateId":"12"}'

SendGrid

curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/projects/me/email-templates/INVITE_TO_PROJECT' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"provider":"sendgrid","templateId":"d-0a1b2c3d4e5f"}'

Resend

curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/projects/me/email-templates/INVITE_TO_PROJECT' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"provider":"resend","templateId":"invite-to-project"}'

SMTP: the subject and HTML go in the body, and are stored with the mapping:

curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/projects/me/email-templates/INVITE_TO_PROJECT' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "provider": "smtp",
    "templateId": "invite",
    "subject": "{{inviterName}} invited you to {{projectName}}",
    "html": "<p>Hi {{firstName}},</p><p><a href=\"{{invitationUrl}}\">Accept the invitation</a></p>"
  }'

Ovok test-renders an SMTP subject and HTML with the template's example parameters before it stores them. A parameter the message does not have, or an unclosed block, answers 422.

4. Check that it is ready

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

Look for your template in mappings and check ready. false means a secret is missing; unmapped lists the names with no mapping.

5. Add languages and domains

Add language and domain to the query to map the same template differently: a German version, or one for a branded site. The mappings sit side by side.

curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/projects/me/email-templates/INVITE_TO_PROJECT?language=de-DE' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"provider":"brevo","templateId":"13"}'

One language and domain use one provider. See how Ovok picks a mapping.

6. Try it

Trigger the flow that sends the message, for example invite a team member to an address you control. If nothing arrives, see troubleshooting.

1. Create the template at your provider​

2. Make sure the provider is configured​

3. Map the template​

4. Check that it is ready​

5. Add languages and domains​

6. Try it​

Related​