Set up email sending

Take a project from no email to a mapped, ready template for each provider, then add languages and domains.

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

Store the provider's credential and, for SendGrid and SMTP, the sender address with POST /v1/email/templates/provider. The mapping routes do not store them. They report whether they are present, as ready, in step 4.

ProviderSecret nameAlso needs a sender address
BrevoBREVO_API_KEYNo
SendGridSENDGRID_API_KEYYes
ResendRESEND_API_KEYNo
SMTPSMTP_URLYes

3. Map the template

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

  1. 1Map the invitation template to SendGrid in English and confirm it is ready.

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 project admin to an address you control. If nothing arrives, see troubleshooting.

Last updated on

On this page