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 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 (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 (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; 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. 
{
  "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:

{
  "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:

{
  "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

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

CLI: keenauth email-provider get