Add Domain
Register a custom sending domain.
POST /api/v1/domains
Registers a new custom domain for sending. Returns the domain record and the DNS records required before the domain can be verified. Authenticate with a JWT.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Domain name (e.g. yourdomain.com) |
Response
Returns 200 OK with a domain object and dns_records:
domain
| Field | Type | Description |
|---|---|---|
id | string | Unique domain ID |
domain | string | Domain name |
status | string | "pending" until verified |
dkim_selector | string | DKIM selector label |
verified_at | string | null | ISO 8601 timestamp when verified |
created_at | string | ISO 8601 timestamp |
dns_records
| Field | Type | Description |
|---|---|---|
verification | DNSRecord | TXT record for ownership proof |
dkim | DNSRecord | TXT record for DKIM signing |
spf | DNSRecord | TXT record for SPF authorisation |
Each DNSRecord has name, type, and value fields.
{
"domain": {
"id": "dom_abc123",
"domain": "yourdomain.com",
"status": "pending",
"dkim_selector": "smail1",
"verified_at": null,
"created_at": "2024-01-15T10:00:00Z"
},
"dns_records": {
"verification": {
"name": "_smail-verification.yourdomain.com",
"type": "TXT",
"value": "smail-verify=abc123xyz"
},
"dkim": {
"name": "smail1._domainkey.yourdomain.com",
"type": "TXT",
"value": "v=DKIM1; k=rsa; p=MIGf..."
},
"spf": {
"name": "yourdomain.com",
"type": "TXT",
"value": "v=spf1 include:spf.smail.dev ~all"
}
}
}Code examples
curl https://api.smail.dev/api/v1/domains \
-H "Authorization: Bearer eyJ..." \
-H "Content-Type: application/json" \
-d '{"domain": "yourdomain.com"}'const result = await smail.domains.add({ domain: "yourdomain.com" });
console.log("Domain ID:", result.domain.id);
console.log("Add these DNS records:", result.dns_records);result, err := client.Domains.Add(ctx, smail.AddDomainRequest{
Domain: "yourdomain.com",
})
fmt.Println("Domain ID:", result.Domain.ID)
fmt.Printf("DNS records: %+v\n", result.DNSRecords)Error responses
| Status | Error | Description |
|---|---|---|
401 | unauthorized | Missing or invalid JWT |
400 | domain already exists | Domain is already registered on this account |
