Email

Create an email connection

Connects your own provider account. provider and what it takes:

  • brevo: credentials.api_key, an API key (Brevo's SMTP key is not accepted).
  • smtp: config host, port (587 or 2525, with STARTTLS) and username; credentials.password.
  • postmark: config.message_stream (default outbound); credentials.server_token.
  • resend: credentials.api_key.
  • ses (Amazon SES): config.region and optionally config.configuration_set; credentials access_key_id and secret_access_key.
  • graph (Microsoft 365): config tenant_id, client_id and sender, the mailbox that sends; credentials.client_secret of an app with the Mail.Send application permission.

Every provider takes config.attachment_budget_bytes and config.max_per_second; reads show them with the provider's defaults filled in. At most 10 connections per workspace; provider can't change later. credentials are encrypted and never returned. Authorize egress_ips at providers that restrict calling IPs (Brevo: Security → Authorized IPs).

post/v1/email-connections

Request

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

Headers

Idempotency-Keystring

Replays the stored response for 24 h; a different body with the same key → 422.

Request body

configobject

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

credentialsobject

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.

namestring required
provider'brevo' | 'smtp' | 'postmark' | 'resend' | 'ses' | 'graph' required

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_tostring 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_recipientstring nullable

The verified address of a workspace member; required with test_mode: redirect.

Response

configobject 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_atstring date-time required
credentials_delete_atstring date-time nullable required

Set after a downgrade: the credentials are deleted then.

egress_ipsstring[] required

The addresses our email traffic leaves from: authorize them at providers that restrict calling IPs (Brevo: Security → Authorized IPs).

eventsobject required

Brevo connections only: the delivery-events webhook in the Brevo account, per region; empty for other providers.

idstring required

emc_…

last_test_atstring date-time nullable required
last_test_status'succeeded' | 'failed' | 'null' nullable required
  • succeeded - succeeded
  • failed - failed
namestring required
objectstring
provider'brevo' | 'smtp' | 'postmark' | 'resend' | 'ses' | 'graph' required
  • brevo - Brevo
  • smtp - SMTP
  • postmark - Postmark
  • resend - Resend
  • ses - Amazon SES
  • graph - Microsoft 365 (Graph)
reply_tostring nullable required
status'active' | 'failing' required
  • active - active
  • failing - failing
test_mode'sandbox' | 'redirect' | 'skip' required
  • sandbox - Sandbox
  • redirect - Redirect
  • skip - Skip
test_recipientstring nullable required
updated_atstring date-time required

Changes

No recorded changes to this operation across all 2 revisions of this API.