---
title: "Test an email connection"
method: POST
path: "/v1/email-connections/{connection_id}/test"
tags: ["Email"]
---

# Test an email connection

`POST /v1/email-connections/{connection_id}/test`

## Request

- Base URL: `https://api-eu.dynamicdocumentapi.com`
- URL: `https://api-eu.dynamicdocumentapi.com/v1/email-connections/{connection_id}/test`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Checks the saved settings from the region that sends, step by step:

* `brevo`: `credentials`, `senders` (the verified senders and domains) and `sandbox_send` (Brevo checks an email from the default sender without delivering it).
* `smtp`: `connect`, `starttls`, `smtp_auth`.
* `postmark`: `credentials`.
* `resend`: `credentials`, which also lists the verified domains.
* `ses`: `credentials`, `senders` (the verified identities; it fails when there are none).
* `graph`: `credentials` (Microsoft Entra ID issues a token).

The senders found are stored as the connection's `senders`. `send_to` adds a real test email (`send`) to a verified member address. `200` with `ok: false` means a step failed; the test stops there. A failed `credentials` or `smtp_auth` step marks the connection `failing`.

## Path parameters

- `connection_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- EmailConnectionTestRequest
  - `send_to` string, nullable: Also send a real test email to this address: the verified address of a workspace member.

## Response `200`

The test ran; check `ok`.

- EmailConnectionTest
  - `connection` EmailConnection, required
    - `config` object, required: The provider's settings (see the write `config`), always with `attachment_budget_bytes` and `max_per_second`: the provider's defaults unless set.
    - `created_at` string, date-time, required
    - `credentials` EmailCredentialsState, required
      - `configured` boolean, required: Credentials are write-only; `false` once they were deleted after a downgrade.
    - `credentials_delete_at` string, date-time, nullable, required: Set after a downgrade: the credentials are deleted then.
    - `default_from` EmailDefaultFrom, required
      - `email` string, required
      - `name` string, nullable, required
    - `egress_ips` string[], required: The addresses our email traffic leaves from: authorize them at providers that restrict calling IPs (Brevo: Security → Authorized IPs).
    - `events` object, required: Brevo connections only: the delivery-events webhook in the Brevo account, per region; empty for other providers.
    - `id` string, required: `emc_…`
    - `last_error` EmailConnectionError, required
      - `at` string, date-time, required
      - `code` string, required: `email_provider_auth_failed`, `email_ip_not_authorized` or `email_credentials_removed`.
      - `message` string, required
    - `last_test_at` string, date-time, nullable, required
    - `last_test_status` 'succeeded' | 'failed' | 'null', nullable, required: * `succeeded` - succeeded * `failed` - failed
    - `name` string, required
    - `object` string
    - `provider` 'brevo' | 'smtp' | 'postmark' | 'resend' | 'ses' | 'graph', required: * `brevo` - Brevo * `smtp` - SMTP * `postmark` - Postmark * `resend` - Resend * `ses` - Amazon SES * `graph` - Microsoft 365 (Graph)
    - `reply_to` string, nullable, required
    - `senders` EmailSender[], required: Verified senders and domains found by the last test.
      - `email` string, required: An address, or the domain for `kind: domain`.
      - `kind` 'sender' | 'domain', required: * `sender` - sender * `domain` - domain
      - `name` string, nullable, required
      - `verified` boolean, required
    - `status` 'active' | 'failing', required: * `active` - active * `failing` - failing
    - `test_mode` 'sandbox' | 'redirect' | 'skip', required: * `sandbox` - Sandbox * `redirect` - Redirect * `skip` - Skip
    - `test_recipient` string, nullable, required
    - `updated_at` string, date-time, required
  - `object` string
  - `ok` boolean, required
  - `senders` EmailSender[], required
    - `email` string, required: An address, or the domain for `kind: domain`.
    - `kind` 'sender' | 'domain', required: * `sender` - sender * `domain` - domain
    - `name` string, nullable, required
    - `verified` boolean, required
  - `steps` EmailTestStep[], required
    - `detail` string, nullable, required
    - `name` string, required: Brevo: `credentials`, `senders`, `sandbox_send`; SMTP: `connect`, `starttls`, `smtp_auth`; Postmark: `credentials`; Resend: `credentials` (also lists the verified domains); Amazon SES: `credentials`, `senders`; Microsoft 365: `credentials` (a token). Then `send` with `send_to`.
    - `ok` boolean, required

## Other responses

- `400`: Invalid request body (`errors[]` with JSON pointers).
- `401`: Missing, invalid, expired or revoked credentials.
- `402`: Email delivery needs the Growth plan or higher (`plan_feature_unavailable`).
- `403`: Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `feature_not_enabled`: email delivery isn't enabled for this workspace yet.
- `404`: Email connection not found.
- `429`: Rate limited (`Retry-After`).
- `503`: The control plane is unreachable (`Retry-After`).

---

[API](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api.md) · [All operations](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api/revisions/0f14bc0000f4?raw)