Domains

Before you can send email from a domain, you must add it and publish DNS records that prove ownership (MX, SPF, DKIM, DMARC).

List Domains

GET /api/v1/domains

Scope: domains:manage

const { data } = await wm.request('GET', '/domains')
console.log(data)

Response

{
  "data": [
    {
      "id": "dom_abc123",
      "name": "wistfare.com",
      "status": "verified",
      "verified": true,
      "records": [
        { "type": "MX",  "name": "wistfare.com", "value": "mail.wistfare.com", "priority": 10, "verified": true },
        { "type": "TXT", "name": "wistfare.com", "value": "v=spf1 a mx ip4:1.2.3.4 ~all", "verified": true },
        { "type": "TXT", "name": "wistmail._domainkey.wistfare.com", "value": "v=DKIM1; k=rsa; p=...", "verified": true },
        { "type": "TXT", "name": "_dmarc.wistfare.com", "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@wistfare.com", "verified": true }
      ],
      "createdAt": "2026-04-01T00:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "hasMore": false
}

Add a Domain

POST /api/v1/domains

Scope: domains:manage

Adds a new domain and returns the DNS records to publish. DKIM keys are generated server-side.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Domain name (e.g., `wistfare.com`)

curl -X POST https://mail.wistfare.com/api/v1/domains \
  -H "X-API-Key: wm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "wistfare.com"}'

Response

{
  "id": "dom_abc123",
  "name": "wistfare.com",
  "status": "pending",
  "verified": false,
  "records": [
    { "type": "MX",  "name": "wistfare.com", "value": "mail.wistfare.com", "priority": 10, "verified": false },
    { "type": "TXT", "name": "wistfare.com", "value": "v=spf1 a mx ip4:1.2.3.4 ~all", "verified": false },
    { "type": "TXT", "name": "wistmail._domainkey.wistfare.com", "value": "v=DKIM1; k=rsa; p=...", "verified": false },
    { "type": "TXT", "name": "_dmarc.wistfare.com", "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@wistfare.com", "verified": false }
  ]
}

Publish each record in your DNS provider, then call the verify endpoint.

Verify DNS Records

POST /api/v1/domains/:id/verify

Scope: domains:manage

Triggers a DNS lookup and updates the mx_verified, spf_verified, dkim_verified, dmarc_verified flags. When all pass, the domain's verified becomes true.

curl -X POST https://mail.wistfare.com/api/v1/domains/dom_abc123/verify \
  -H "X-API-Key: wm_your_api_key"

Response

{
  "id": "dom_abc123",
  "verified": true,
  "mxVerified": true,
  "spfVerified": true,
  "dkimVerified": true,
  "dmarcVerified": true
}

Delete a Domain

DELETE /api/v1/domains/:id

Scope: domains:manage

Removes the domain and cascades delete to all mailboxes under it. This is irreversible.

curl -X DELETE https://mail.wistfare.com/api/v1/domains/dom_abc123 \
  -H "X-API-Key: wm_your_api_key"

Returns { "ok": true }.

On this page