SendingDomains_create
const url = 'http://localhost:3000/api/sending-domains';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"domain":"example","dkimSelector":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:3000/api/sending-domains \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "domain": "example", "dkimSelector": "example" }'Create a resource
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Add a Sending domain; mints the DKIM keypair and returns the DNS records to publish.
object
The domain to authenticate, e.g. “mail.acme.com” (normalized to lowercase ASCII)
DKIM selector; defaults to “sphericon” when omitted
Example generated
{ "domain": "example", "dkimSelector": "example"}Responses
Section titled “Responses”The request has succeeded and a new resource has been created as a result.
Sending domain (ADR 0010). sphericon generates the DKIM keypair; the caller publishes the
DKIM TXT record. The private key is never returned. verified is a live property
re-checked in the background: it can flip back if the DNS record disappears.
object
Unique identifier
The authenticated domain, e.g. “mail.acme.com”
DKIM selector; the record host is “
Whether the DKIM DNS is currently published and matches our key
The required DKIM TXT record
object
The record type (always TXT for the records we generate)
The host / name to create the record at
The record value to publish
The suggested SPF TXT record (advisory: does not gate sending)
object
The record type (always TXT for the records we generate)
The host / name to create the record at
The record value to publish
The suggested DMARC TXT record (advisory bulk-readiness signal)
object
The record type (always TXT for the records we generate)
The host / name to create the record at
The record value to publish
The Tracking domain CNAME; absent when the instance has no tracking target configured
object
The record type (always CNAME)
The host to create the record at: “track.” followed by the domain
The edge host the CNAME must point at
Where the Tracking domain stands
Why the domain is not advancing; absent when nothing holds it back
When the Tracking domain was most recently checked (null = never)
When the state most recently changed (null = never)
When the DKIM DNS was most recently checked (null = never)
When the domain most recently became verified (null = never)
Creation timestamp
Last update timestamp
Example
{ "dkimRecord": { "type": "TXT" }, "spfRecord": { "type": "TXT" }, "dmarcRecord": { "type": "TXT" }, "trackingRecord": { "type": "CNAME", "state": "pending", "reason": "host_taken" }}RFC 7807 bad request response
RFC 7807 Problem Details
object
Why the request was refused, when the client should act on it
A URI reference that identifies the problem type
A short, human-readable summary of the problem type
HTTP status code
A human-readable explanation specific to this occurrence
A URI reference that identifies the specific occurrence
Validation errors grouped by field
object
Form-level validation error
Field validation errors
object
Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait
Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)
object
The error that failed the request, or the panic value
The goroutine stack of a panic; absent for an error a handler returned
The request id the server log carries for this request
The HTTP method of the failed request
The path of the failed request
Example
{ "code": "second_factor_required"}RFC 7807 unauthorized response
RFC 7807 Problem Details
object
Why the request was refused, when the client should act on it
A URI reference that identifies the problem type
A short, human-readable summary of the problem type
HTTP status code
A human-readable explanation specific to this occurrence
A URI reference that identifies the specific occurrence
Validation errors grouped by field
object
Form-level validation error
Field validation errors
object
Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait
Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)
object
The error that failed the request, or the panic value
The goroutine stack of a panic; absent for an error a handler returned
The request id the server log carries for this request
The HTTP method of the failed request
The path of the failed request
Example
{ "code": "second_factor_required"}RFC 7807 conflict response
RFC 7807 Problem Details
object
Why the request was refused, when the client should act on it
A URI reference that identifies the problem type
A short, human-readable summary of the problem type
HTTP status code
A human-readable explanation specific to this occurrence
A URI reference that identifies the specific occurrence
Validation errors grouped by field
object
Form-level validation error
Field validation errors
object
Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait
Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)
object
The error that failed the request, or the panic value
The goroutine stack of a panic; absent for an error a handler returned
The request id the server log carries for this request
The HTTP method of the failed request
The path of the failed request
Example
{ "code": "second_factor_required"}RFC 7807 validation response
RFC 7807 Problem Details
object
Why the request was refused, when the client should act on it
A URI reference that identifies the problem type
A short, human-readable summary of the problem type
HTTP status code
A human-readable explanation specific to this occurrence
A URI reference that identifies the specific occurrence
Validation errors grouped by field
object
Form-level validation error
Field validation errors
object
Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait
Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)
object
The error that failed the request, or the panic value
The goroutine stack of a panic; absent for an error a handler returned
The request id the server log carries for this request
The HTTP method of the failed request
The path of the failed request
Example
{ "code": "second_factor_required"}RFC 7807 too many requests response: a rate limit was exceeded (ADR 0025)
RFC 7807 Problem Details
object
Why the request was refused, when the client should act on it
A URI reference that identifies the problem type
A short, human-readable summary of the problem type
HTTP status code
A human-readable explanation specific to this occurrence
A URI reference that identifies the specific occurrence
Validation errors grouped by field
object
Form-level validation error
Field validation errors
object
Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait
Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)
object
The error that failed the request, or the panic value
The goroutine stack of a panic; absent for an error a handler returned
The request id the server log carries for this request
The HTTP method of the failed request
The path of the failed request
Example
{ "code": "second_factor_required"}Headers
Section titled “Headers”Seconds to wait before retrying
The request budget of the window that was exceeded
Requests left in the current window
Unix time at which the window resets