Register a sending domain with a connected provider
Registers a sending domain and asks the named provider to verify it. Registering a domain that is already registered RE-ASKS the provider and refreshes what is stored, which is how a verification that finished later becomes visible, so a repeat is the retry rather than a mistake. provider must name a connection this store already has AND has enabled. A store with no enabled connection is refused rather than handed a registration no provider has been told about. THE RESPONSE CARRIES THE DKIM RECORD the provider issued, which is the point of the call: publish it in the domain’s DNS. It cannot be sent IN. Expect status pending. Verification finishes in DNS, not here.
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Body
AN UPSERT. Registering a domain that is already registered re-asks the provider and refreshes what is stored, so a repeat is the retry rather than a conflict. dkim_record and status are REFUSED BY NAME rather than ignored. The record is the provider's own instruction, and one accepted from a caller could be an attacker's signing key published in the merchant's DNS on this API's say-so; the status is the provider's verdict, recorded through PUT /api/v1/email-domains/{domain} once you have it.
Which connected relay is asked to verify. It must name a connection this store has AND has enabled, or the call is refused 404 rather than storing a registration no provider knows about. List them at /api/v1/email-providers.
The sending domain, for example mail.example.com.
Response
Created
