# Get the email provider

`GET /v1/email-provider` · permission `email-provider:read` · all plans

Returns how the environment sends email: the delivery mode, the sender address, your own SMTP server or email provider, and the last connection test.

The credential (SMTP password or API key) is never returned, not even masked or as a length. `credentials_set` only says whether one is stored.

An environment that has never been configured returns `platform_default` with version `0`. The `ETag` header carries the version; send it as `If-Match` when you [replace](put.md) the configuration.

## Response

`200 OK` with the configuration and `ETag` set to its version.

| Field | Type | Description |
|---|---|---|
| `mode` | string | `platform_default`, `platform_managed_domain`, `customer_smtp`, `customer_api` or `customer_webhook`. |
| `sender_domain_id` | string or null | `platform_managed_domain`: the [sender domain](../email-sender-domains/get.md) (`sdom_…`) mail is sent from; null in every other mode. Read the domain to see its current status. |
| `webhook_endpoint_id` | string or null | `customer_webhook`: the [webhook endpoint](../webhook-endpoints/get.md) (`whe_…`) that receives the rendered messages; null in every other mode. Read the endpoint to see whether it is still enabled. |
| `from_address` | string or null | Bare sender address; null in `platform_default`. |
| `reply_to` | string or null | Bare reply-to address. |
| `provider` | string or null | `customer_api` provider: `ses`, `sendgrid`, `postmark`, `mailgun` or `brevo`. |
| `smtp_host` | string or null | `customer_smtp` server host name. |
| `smtp_port` | integer or null | `customer_smtp` port: `465` (implicit TLS) or `587` (STARTTLS). |
| `smtp_username` | string or null | `customer_smtp` AUTH user name. It is not secret. |
| `credentials_set` | boolean | Whether a credential is stored. |
| `last_test_at` | string or null | Time of the last [connection test](test.md); cleared when the configuration changes. |
| `last_test_result` | string or null | `ok` or the fixed error code of the last test. |
| `version` | integer | Configuration version, the same as the `ETag`; `0` means never configured. |
| `updated_at` | string or null | Time of the last change. |

```json
{
  "mode": "customer_smtp",
  "sender_domain_id": null,
  "webhook_endpoint_id": null,
  "from_address": "no-reply@example.com",
  "reply_to": null,
  "provider": null,
  "smtp_host": "smtp.example.com",
  "smtp_port": 587,
  "smtp_username": "mailer",
  "credentials_set": true,
  "last_test_at": "2026-10-19T09:30:00Z",
  "last_test_result": "ok",
  "version": 4,
  "updated_at": "2026-10-19T09:00:00Z"
}
```

A `platform_managed_domain` configuration:

```json
{
  "mode": "platform_managed_domain",
  "sender_domain_id": "sdom_01k7xq3m5r8t9v0w1x2y3z4a5b",
  "webhook_endpoint_id": null,
  "from_address": "auth@mail.example.com",
  "reply_to": "support@example.com",
  "provider": null,
  "smtp_host": null,
  "smtp_port": null,
  "smtp_username": null,
  "credentials_set": false,
  "last_test_at": null,
  "last_test_result": null,
  "version": 5,
  "updated_at": "2026-10-19T10:00:00Z"
}
```

A `customer_webhook` configuration:

```json
{
  "mode": "customer_webhook",
  "sender_domain_id": null,
  "webhook_endpoint_id": "whe_01k7xq3m5r8t9v0w1x2y3z4a5b",
  "from_address": "auth@example.com",
  "reply_to": null,
  "provider": null,
  "smtp_host": null,
  "smtp_port": null,
  "smtp_username": null,
  "credentials_set": false,
  "last_test_at": null,
  "last_test_result": null,
  "version": 6,
  "updated_at": "2026-10-27T09:00:00Z"
}
```

## Errors

| HTTP | code | When |
|---|---|---|
| 401 | `unauthenticated` | The credential is missing, invalid or revoked. |
| 403 | `insufficient_permissions` | The credential lacks the required permission. |
| 429 | `rate_limited` | The rate limit was exceeded; retry after the `Retry-After` period. |
| 503 | `service_unavailable` | A dependency is temporarily unavailable; retry after the `Retry-After` period. |

## Example

```bash
curl https://api.eu.keenauth.com/v1/email-provider \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

CLI: `keenauth email-provider get`