Add a sending domain
Registers a domain for sending and returns it with the DNS records required to verify ownership and configure DKIM.
Registers a domain for sending and returns it with the DNS records required to verify ownership and configure DKIM. Responds with 201. Supplying a connection attaches the domain to that DNS account; the domain must sit inside the zone given with it. When Samva cannot register another sending domain right now, this responds with 429 and no domain is created. A banned organization is refused with 403. namespaceId places the domain in a namespace, and only that namespace's keys and organization-wide callers reach it; a namespace-scoped key always adds to its own namespace.
apiKeyx-api-key<token>application/json- body
domain*stringconnection?|nullnamespaceId?|nullshared?boolean|nullSuccess
application/json- response
unknownRecipientMailboxId*|The active mailbox on this domain that receives unknown addresses when catch-all has no webhook endpoint, or null to drop them without a bounce.
id*EmailDomainId^dom_[0-9a-hjkmnp-tv-z]{16,24}$domain*stringphase*string"dns-setup""provisioning""verifying""ready""degraded""failed"dkimSelector?string|nulldkimPublicKey?string|nulldnsRecords*array<>verifiedAt*string|nullnamespaceId*|The namespace the domain belongs to, or null at organization level. Namespace callers also reach organization-level domains whose shared flag is true.
shared*booleanisDefault*booleandeliverability*Bounce and complaint rates over the last 24 hours, as fractions between 0 and 1, with windowSends, the deliveries they were divided by, plus sendingStatus, which says whether the organization can currently send. The window matches the one the sending-pause rule reads. Below 200 sends that rule ignores the window entirely, so a rate over a smaller windowSends is a quotient rather than a reading. These are not a lifetime record; an identity with no traffic in the window reports zeroes.
createdAt*stringupdatedAt*stringimport { createClient } from "samva";
const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });
const result = await samva.email.addDomain({
"domain": "example"
});{
"unknownRecipientMailboxId": "string",
"id": "string",
"domain": "string",
"phase": "dns-setup",
"dkimSelector": "string",
"dkimPublicKey": "string",
"dnsRecords": [
{
"type": "A",
"name": "string",
"value": "string",
"ttl": "string",
"description": "string",
"priority": 0
}
],
"verifiedAt": "string",
"namespaceId": "string",
"shared": true,
"isDefault": true,
"deliverability": {
"bounceRate": 0,
"complaintRate": 0,
"windowSends": 0,
"sendingStatus": "enabled"
},
"createdAt": "string",
"updatedAt": "string"
}