# Configure an email provider

Canonical page: https://docs.ovok.com/email-templates/email-providers

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.

```bash
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 [#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 |

```bash
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:

```json
{
  "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](/email-templates/set-up-email#6-try-it).

<Callout type="warn">`from` is one address for the whole project: sending it changes the sender for every provider, Brevo and Resend included.</Callout>

## Check which providers can send [#check-which-providers-can-send]

```bash
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 [#change-a-provider]

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

```bash
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 [#errors]

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

| Status | Code | Cause |
| --- | --- | --- |
| [`400`](/errors/malformed-request) | none | The token carries no project. |
| [`401`](/errors/unauthenticated) | none | The bearer token is missing or invalid. |
| [`403`](/errors/forbidden) | none | The caller is not a project admin. |
| [`404`](/errors/not-found) | [`PROVIDER_NOT_CONFIGURED`](/errors/provider-not-configured) | `PATCH` for a provider that is not set up. Set it up with `POST`. |
| [`409`](/errors/conflict) | [`PROVIDER_CONFIGURED`](/errors/provider-configured) | `POST` for a provider that is already set up. Use `PATCH`. |
| [`409`](/errors/conflict) | none | The project changed while Ovok wrote. Read it again and retry. |
| [`422`](/errors/validation-failed) | [`INVALID_SECRET`](/errors/invalid-secret) | The secret is not one the provider takes. |
| [`422`](/errors/validation-failed) | [`FROM_REQUIRED`](/errors/from-required) | `POST` for SendGrid or SMTP when the project has no sender address and the body has no `from`. |
| [`422`](/errors/validation-failed) | none | The body fails validation, for example an unknown field or a `PATCH` with neither `secret` nor `from`. |
| [`503`](/errors/service-unavailable) | [`ENCRYPTION_UNAVAILABLE`](/errors/encryption-unavailable) | The server cannot encrypt secrets, so nothing is stored. |

## Related [#related]

- [Set up email sending](/email-templates/set-up-email)
- [Map templates with the API](/email-templates/map-templates)
- [Troubleshooting](/email-templates/troubleshooting)
