---
title: "Update an email connection"
method: PATCH
path: "/v1/email-connections/{connection_id}"
tags: ["Email"]
---

# Update an email connection

`PATCH /v1/email-connections/{connection_id}`

## Request

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

Partial update; a body without `credentials` keeps them. A `config` replaces the stored one as a whole. `provider` is immutable.

## Path parameters

- `connection_id` string, required

## Request body

- PatchedEmailConnectionWrite
  - `config` object: Per provider: SMTP `{host, port, username}` (port 587 or 2525); Postmark `{message_stream}` (default `outbound`, also when empty or null); Amazon SES `{region, configuration_set?}`; Microsoft 365 `{tenant_id, client_id, sender}` (`sender`: the mailbox that sends); Brevo and Resend none. Every provider: `attachment_budget_bytes`, the bytes of files attached per email (default / maximum: Brevo 10 / 13 MiB, SMTP 6 / 25 MiB, Postmark 6 / 6 MiB, Resend 10 / 25 MiB, Amazon SES 10 / 25 MiB, Microsoft 365 2 / 2 MiB), and `max_per_second` (1 to 100, default 10).
  - `credentials` object: Write-only: Brevo `{api_key}` (an API key, not its SMTP key), SMTP `{password}`, Postmark `{server_token}`, Resend `{api_key}`, Amazon SES `{access_key_id, secret_access_key}`, Microsoft 365 `{client_secret}`. A PATCH without them keeps them.
  - `default_from` EmailDefaultFromWrite
    - `email` string, required: One address: the sender of rules without their own.
    - `name` string, nullable
  - `name` string
  - `provider` 'brevo' | 'smtp' | 'postmark' | 'resend' | 'ses' | 'graph': `brevo`, `smtp`, `postmark`, `resend`, `ses` (Amazon SES) or `graph` (Microsoft 365); it can't change after creation. * `brevo` - Brevo * `smtp` - SMTP * `postmark` - Postmark * `resend` - Resend * `ses` - Amazon SES * `graph` - Microsoft 365 (Graph)
  - `reply_to` string, nullable
  - `test_mode` 'sandbox' | 'redirect' | 'skip': Test renders: `sandbox` (Brevo only, and its default: Brevo checks the email without delivering it), `redirect` (to `test_recipient`, subject prefixed `[Test] `), `skip` (no provider call; the default for every other provider). * `sandbox` - Sandbox * `redirect` - Redirect * `skip` - Skip
  - `test_recipient` string, nullable: The verified address of a workspace member; required with `test_mode: redirect`.

## Response `200`

- EmailConnection
  - `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

## 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)