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

Access

The Domains endpoints power the MisarMail dashboard and the MCP server tools list_domains, add_domain, and verify_domain. Base URL: https://api.misar.io/mail. Every account gets a verified @misar.io address for free; adding a custom domain is gated by your plan's custom_domains limit.

Endpoints

Method	Path	Description
`GET`	`/mail/domains`	List custom domains (optional `?status=` filter)
`POST`	`/mail/domains`	Add a domain and get DNS records
`POST`	`/mail/domains/:id/verify`	Trigger DNS verification
`DELETE`	`/mail/domains?id=<uuid>`	Remove a domain

List domains

GET/mail/domains

List all custom domains for the account. For @misar.io users, a virtual, always-verified misar.io entry (id virtual-misar-io, is_platform_domain: true) is prepended.

Query parameters

statusstringquery

Filter by status: pending, verified, or failed. Any other value returns 400.

Response fields

successboolean

true when the request succeeded.

domainsArray<Domain>

Each domain includes id, domain, status (pending | verified | failed), verification_record, spf_record, spf_status, dkim_selector, dkim_public_key, dkim_record, dkim_status, dmarc_record, dmarc_status, mx_record, mx_status, is_active, verified_at, verification_errors, created_at, and updated_at.

Request

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

200 — OK

{
  "success": true,
  "domains": [
    {
      "id":            "550e8400-e29b-41d4-a716-446655440000",
      "domain":        "yourdomain.com",
      "status":        "verified",
      "spf_status":    "verified",
      "dkim_selector": "dkim",
      "dkim_status":   "verified",
      "dmarc_status":  "verified",
      "mx_record":     "10 mail.misar.io",
      "mx_status":     "verified",
      "is_active":     true,
      "verified_at":   "2026-02-10T09:00:00Z",
      "created_at":    "2026-02-10T08:00:00Z",
      "updated_at":    "2026-02-10T09:00:00Z"
    }
  ]
}

Add a domain

POST/mail/domains

Add a new custom domain. Returns the domain record plus DNS setup instructions. Subject to your plan's custom_domains limit.

Request body

domainstringbodyrequired

Root domain or subdomain (e.g. yourdomain.com or mail.yourdomain.com). Lower-cased server-side.

Response fields

successboolean

true when the domain was added.

domainobject

The created domain row, including its generated spf_record, dkim_selector (dkim), dmarc_record, and mx_record.

dnsRecordsobject

Human-readable DNS setup instructions for the DKIM, SPF, DMARC, and MX records to publish.

Request

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

201 — Created

{
  "success": true,
  "domain": {
    "id":            "550e8400-e29b-41d4-a716-446655440000",
    "domain":        "yourdomain.com",
    "status":        "pending",
    "spf_record":    "v=spf1 ip4:144.76.166.41 ip4:198.23.249.218 ~all",
    "dkim_selector": "dkim",
    "dmarc_record":  "v=DMARC1; p=quarantine; rua=mailto:dmarc@misar.io",
    "mx_record":     "10 mail.misar.io"
  },
  "dnsRecords": {
    "dkim":  { "type": "TXT", "host": "dkim._domainkey.yourdomain.com", "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb..." },
    "spf":   { "type": "TXT", "host": "yourdomain.com", "value": "v=spf1 ip4:144.76.166.41 ip4:198.23.249.218 ~all" },
    "dmarc": { "type": "TXT", "host": "_dmarc.yourdomain.com", "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@misar.io" },
    "mx":    { "type": "MX", "host": "yourdomain.com", "value": "mail.misar.io", "priority": 10 }
  }
}

409 — Unavailable

{ "error": "This domain is unavailable" }

DNS changes can take up to 48 hours to propagate. Call POST /mail/domains/:id/verify once records are published to trigger an immediate check.

Verify a domain

POST/mail/domains/:id/verify

Run an immediate DNS verification. On full success the domain is activated, any pending aliases on it become active, and a dedicated transactional SMTP pool is auto-created for the domain.

Path parameters

idUUIDpathrequired

ID of the domain to verify.

Response fields

domainobject

The updated domain row with refreshed status and per-record statuses.

resultsArray<DnsCheckResult>

Per-record check results (SPF, DKIM, DMARC, MX) with any error messages.

verifiedboolean

true when all required records passed.

messagestring

Human-readable summary.

Request

curl -X POST https://api.misar.io/mail/domains/550e8400-e29b-41d4-a716-446655440000/verify \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

200 — OK

{
  "domain": {
    "id":     "550e8400-e29b-41d4-a716-446655440000",
    "domain": "yourdomain.com",
    "status": "verified"
  },
  "results": [
    { "record": "spf",   "valid": true },
    { "record": "dkim",  "valid": true },
    { "record": "dmarc", "valid": true },
    { "record": "mx",    "valid": true }
  ],
  "verified": true,
  "message": "Domain verified successfully!"
}

Remove a domain

DELETE/mail/domains

Remove a custom domain. The domain id is passed as a query parameter, not a path segment. A domain that still has active aliases cannot be deleted.

Query parameters

idUUIDqueryrequired

ID of the domain to remove.

Response fields

successboolean

true when the domain was removed.

Request

curl -X DELETE "https://api.misar.io/mail/domains?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

200 — OK

{ "success": true }

Status codes

200 — OK. List, verify, or delete succeeded.
201 — Created. Domain added.
400 — Bad request. Invalid ?status filter, invalid/missing domain id, Validation error on the domain string, or Cannot delete domain with active aliases.
401 — Unauthorized. No authenticated session / API key.
403 — Forbidden. Domain does not belong to you, or your plan's custom_domains limit is reached.
404 — Not found. Domain does not exist.
409 — Conflict. This domain is unavailable (already registered).

Required DNS Records

Record	Type	Purpose
`dkim._domainkey.yourdomain.com`	TXT	DKIM signing key
`yourdomain.com`	TXT	SPF — authorizes MisarMail sending IPs
`_dmarc.yourdomain.com`	TXT	DMARC policy
`yourdomain.com`	MX	Routes replies to the MisarMail inbox (`10 mail.misar.io`)

The generated SPF record lists MisarMail's sending IPs directly (v=spf1 ip4:… ~all). If you already have an SPF record, merge the two rather than publishing a second one — multiple SPF records on one host cause failures.

Custom Domains

Endpoints

List domains

Add a domain

Verify a domain

Remove a domain

Status codes

Required DNS Records

On this page