Domains

Add a sending domain

Register a domain and start SES DKIM verification. The response carries the identity as created — verified is false, because nothing is verified until the DKIM records are published in the domain's DNS and SES resolves them. Poll /api/v1/domains/{id}/verify after publishing them.

region pins the SES region. The first domain a project adds LOCKS the project to that region and every later domain must match it — a project split across regions would have its SES configuration diverge silently.

stream assigns the identity to transactional or marketing traffic at creation; omit it to leave the identity serving both. stream_default makes it the project's default for that stream and therefore requires stream — sending it alone answers 422 validation_error rather than being ignored.

A host already registered — to this project or to another — answers 409 conflict when the caller can already send from it and 403 project_access_denied when it belongs elsewhere. A subdomain whose registrable root is held by a suspended project is refused the same way.

Requires the domains:write scope — Add and remove sending domains, and trigger verification.

post/api/v1/domains

Request

  • Base URL: https://api.sendly.now
  • URL: https://api.sendly.now/api/v1/domains
  • Auth: one of:
    • HTTP bearer
    • API key in cookie better-auth.session_token
    • OAuth 2 (authorization code, authorization URL https://app.sendly.now/api/auth/oauth2/authorize, token URL https://app.sendly.now/api/auth/oauth2/token, scopes: domains:write)

Request body

domainstring required
region'us-east-1' | 'us-west-2' | 'eu-west-1'

AWS SES region for the project. Once a domain is added the region is locked and cannot be changed.

stream'TRANSACTIONAL' | 'MARKETING'

Which traffic a sending identity carries. An identity with no stream serves both, which is how every domain added before per-stream identities behaves.

stream_defaultboolean

Make this the project's default identity for stream. Requires stream.

Response

The registered sending domain, awaiting DNS

created_atstring date-time required
default_from_addressstring nullable required
default_from_namestring nullable required

The display name recipients see beside any address on this domain when a send names none. null falls back to the project name.

dkim_verifiedboolean required
domainstring required
idstring uuid required
mail_from_domainstring nullable required
mail_from_domain_statusstring nullable required

SES's CustomMailFromStatus for mail_from_domain — the subdomain that carries the bounce path, NOT the status of any From address.

regionstring nullable required
stream'TRANSACTIONAL' | 'MARKETING' nullable required

Which traffic a sending identity carries. An identity with no stream serves both, which is how every domain added before per-stream identities behaves.

stream_defaultboolean required
updated_atstring date-time required
verifiedboolean required

Changes

No recorded changes to this operation across all 1 revision of this API.