Custom Domains

Custom domains let you send email from your own domain (e.g. [email protected]) with proper DKIM signing for improved deliverability. Each domain must pass DNS verification before it can be used.

Auth scope: domains

Plan Limits

| Plan | Custom Domains | |------|---------------| | Free | 0 | | Pro | 3 | | Max | 10 | | Enterprise | Unlimited |

Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /api/v1/domains | List custom domains | | POST | /api/v1/domains | Add a domain | | GET | /api/v1/domains/:id | Get domain status and DNS records | | POST | /api/v1/domains/:id/verify | Trigger DNS verification | | DELETE | /api/v1/domains/:id | Remove a domain |

GET /api/v1/domains

List all custom domains for the authenticated account.

curl https://api.misar.io/mail/v1/domains \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Response

{
  "success": true,
  "domains": [
    {
      "id":          "dom_abc123",
      "domain":      "yourdomain.com",
      "status":      "verified",
      "dkim_status": "valid",
      "spf_status":  "valid",
      "dmarc_status":"valid",
      "created_at":  "2026-02-10T08:00:00Z"
    }
  ]
}

POST /api/v1/domains

Add a new custom domain. Returns the DNS records to configure.

curl -X POST https://api.misar.io/mail/v1/domains \
  -H "Authorization: Bearer msk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "yourdomain.com" }'

Request Fields

| Field | Type | Required | Notes | |-------|------|----------|-------| | domain | string | ✓ | Root domain or subdomain (e.g. mail.yourdomain.com) |

Response

{
  "success": true,
  "domain": {
    "id":     "dom_abc123",
    "domain": "yourdomain.com",
    "status": "pending",
    "dns_records": {
      "dkim": {
        "type":  "TXT",
        "host":  "mm._domainkey.yourdomain.com",
        "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb..."
      },
      "spf": {
        "type":  "TXT",
        "host":  "yourdomain.com",
        "value": "v=spf1 include:spf.misar.io ~all"
      },
      "dmarc": {
        "type":  "TXT",
        "host":  "_dmarc.yourdomain.com",
        "value": "v=DMARC1; p=quarantine; rua=mailto:[email protected]"
      },
      "mx": {
        "type":     "MX",
        "host":     "yourdomain.com",
        "value":    "mail.misar.io",
        "priority": 10
      }
    }
  }
}

GET /api/v1/domains/:id

Get the current status and DNS record details for a domain.

curl https://api.misar.io/mail/v1/domains/dom_abc123 \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Domain status values

| Status | Meaning | |--------|---------| | pending | Added but DNS not yet verified | | verified | All DNS records valid — domain ready to send | | failed | One or more DNS records missing or invalid |

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

Trigger an immediate DNS verification check. Use this after publishing DNS records to avoid waiting for the automatic daily check.

curl -X POST https://api.misar.io/mail/v1/domains/dom_abc123/verify \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Response

{
  "success": true,
  "domain": {
    "id":           "dom_abc123",
    "domain":       "yourdomain.com",
    "status":       "verified",
    "dkim_status":  "valid",
    "spf_status":   "valid",
    "dmarc_status": "valid"
  }
}

DELETE /api/v1/domains/:id

Remove a custom domain. Existing campaigns that reference this domain will fall back to the default MisarMail sending domain.

curl -X DELETE https://api.misar.io/mail/v1/domains/dom_abc123 \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Response

{ "success": true }

Required DNS Records

| Record | Type | Purpose | |--------|------|---------| | mm._domainkey.yourdomain.com | TXT | DKIM signing key | | yourdomain.com | TXT | SPF — authorizes MisarMail IPs | | _dmarc.yourdomain.com | TXT | DMARC policy | | yourdomain.com | MX | Routes replies to MisarMail inbox |