# Set up an email provider

Canonical page: https://docs.ovok.com/api/email/set-up-an-email-provider

`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

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