Channels

Manage email channel configurations for your workspace, including SES domain setup and DNS verification.

The Channels API lets you configure email sending and receiving infrastructure for your workspace. Each channel setup connects your workspace to an email domain, handles domain verification, and manages the DNS records required for authenticated email delivery.

SES Setup

SES setup resources represent verified email domains. Each setup provisions an isolated email tenant and a domain identity, then returns the DNS records your team must publish to complete verification.

Once DNS records are published, the platform confirms verification automatically on subsequent reads or explicit verify calls.

Endpoints

Method	Path	Description
POST	/v1/{workspace_id}/channels/ses-setup	Create an SES setup
GET	/v1/{workspace_id}/channels/ses-setup	List SES setups (paginated)
GET	/v1/{workspace_id}/channels/ses-setup/{setup_id}	Get an SES setup with live DNS refresh
POST	/v1/{workspace_id}/channels/ses-setup/{setup_id}/verify	Refresh DNS verification status
DELETE	/v1/{workspace_id}/channels/ses-setup/{setup_id}	Delete an SES setup

Create an SES Setup

POST /v1/{workspace_id}/channels/ses-setup

Creates an email tenant and domain identity for the workspace. Returns the full setup detail including DNS records that must be published at your DNS provider.

Request body:

Field	Type	Required	Description
tenant_name	string	Yes	Logical tenant name for email reputation isolation. 1-64 characters, alphanumeric plus hyphens and underscores ([A-Za-z0-9_-]). Must be unique.
domain_identity	string	Yes	Domain to verify for sending and receiving (e.g. mail.customer.com). 1-255 characters.

Response: 201 Created - Returns an SES Setup Detail object.

Error responses:

Status	Description
409	Tenant name or domain identity already exists.
422	Invalid tenant name or domain identity format.
502	Upstream email service unavailable.
504	Upstream email service timed out.

Permissions: Requires Channel.create.

List SES Setups

GET /v1/{workspace_id}/channels/ses-setup

Returns a paginated list of SES setups owned by the workspace. Each item includes a cached dns_verified aggregate. Use the GET detail endpoint for per-record DNS status.

Supports standard pagination query parameters (limit, continuation_token).

Response: Paginated list of SES Setup List Item objects.

Permissions: Requires Channel.view.

Get an SES Setup

GET /v1/{workspace_id}/channels/ses-setup/{setup_id}

Returns the full SES setup detail including per-record DNS verification status. Each call triggers a live DNS lookup, so the verified flag on each record reflects the current state.

Response: Returns an SES Setup Detail object.

Error responses:

Status	Description
404	SES setup not found in this workspace.

Permissions: Requires Channel.view.

Verify DNS

POST /v1/{workspace_id}/channels/ses-setup/{setup_id}/verify

Explicit DNS verification refresh. Functionally equivalent to the GET endpoint but exposed as a POST so "Verify now" actions in your UI read as intentional operations rather than passive reads.

Response: Returns an SES Setup Detail object.

Error responses:

Status	Description
404	SES setup not found in this workspace.

Permissions: Requires Channel.view.

Delete an SES Setup

DELETE /v1/{workspace_id}/channels/ses-setup/{setup_id}

Tears down the upstream email tenant and domain identity and removes the workspace binding. Deletion is refused if any use case still references the setup - delete those first.

Response: 204 No Content

Error responses:

Status	Description
404	SES setup not found in this workspace.
409	Setup still referenced by active use cases. Delete those first.
502	Upstream email service unavailable.
504	Upstream email service timed out.

Permissions: Requires Channel.delete.

Models

SES Setup Detail

Field	Type	Description
id	string (UUID)	Unique identifier for the SES setup.
tenant_name	string	Logical tenant name.
domain_identity	string	Verified domain.
dns_checked_at	datetime or null	Timestamp of the last DNS verification check.
dns_records	array of DNS Record	DNS records to publish, with per-record verification status.
created_at	datetime	When the setup was created.
updated_at	datetime	When the setup was last modified.

SES Setup List Item

Field	Type	Description
id	string (UUID)	Unique identifier for the SES setup.
tenant_name	string	Logical tenant name.
domain_identity	string	Verified domain.
dns_verified	boolean	Aggregate verification status - true when all DNS records are verified.
dns_checked_at	datetime or null	Timestamp of the last DNS verification check.
created_at	datetime	When the setup was created.
updated_at	datetime	When the setup was last modified.

DNS Record

Field	Type	Description
address	string	Fully-qualified hostname where the DNS entry must be published.
record	string	Target value to publish at your DNS provider.
type	string	Record type: CNAME, MX, or TXT.
verified	boolean	Whether the live DNS lookup found this entry.