Domains

Before you can send emails, you need to add and verify a custom domain. Smail uses DNS records to authenticate your emails with SPF, DKIM, and a verification TXT record.

How it works

Add your domain — call POST /api/v1/domains with your domain name
Configure DNS — add the three DNS records returned in the response
Verify — call POST /api/v1/domains/:id/verify to trigger a live DNS check

Step 1: Add your domain

import { SmailClient } from "@smail/smail-js";

const smail = new SmailClient({ apiKey: process.env.SMAIL_API_KEY! });

const result = await smail.domains.add({ domain: "yourdomain.com" });

console.log("Domain ID:", result.domain.id);
console.log("DNS records:", result.dns_records);

result, err := client.Domains.Add(ctx, smail.AddDomainRequest{
    Domain: "yourdomain.com",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("Domain ID:", result.Domain.ID)
fmt.Printf("DNS records: %+v\n", result.DNSRecords)

Step 2: Configure DNS

The response includes three DNS records to add to your domain registrar:

Record	Type	Purpose
`verification`	TXT	Proves domain ownership
`dkim`	TXT	Signs outgoing emails
`spf`	TXT	Authorises Smail to send on your behalf

Each record has a name, type, and value field. Add all three to your DNS provider before verifying.

Step 3: Verify your domain

const verified = await smail.domains.verify("dom_abc123");
console.log("Status:", verified.domain.status); // "verified"

verified, err := client.Domains.Verify(ctx, "dom_abc123")
if err != nil {
    log.Fatal(err) // error detail explains which record is missing
}
fmt.Println("Status:", verified.Domain.Status) // "verified"

DNS propagation can take up to 48 hours. If verification fails, the error message indicates which record is missing or incorrect.

Domain status

Status	Meaning
`pending`	Domain added but not yet verified
`verified`	DNS records confirmed — ready to send