DNS Checks

Trigger and retrieve DNS security checks for your domains.

Run DNS Checks

Triggers a complete DNS security check for a domain and stores the results. MailShield also checks every domain every 2 hours, so call this after you change DNS rather than on a schedule. This endpoint is rate limited to 5 checks per minute per domain.

POST /api/v1/domains/{id}/checks

Path Parameters

Parameter	Type	Description
id	uuid	Domain ID

Response

Returns the results of all DNS checks:

{
  "data": {
    "checkedAt": "2024-01-15T10:30:00Z",
    "results": {
      "mx": {
        "records": [
          {"priority": 10, "exchange": "mail.example.com"}
        ],
        "hosts": [...],
        "tlsSupported": true,
        "daneSupported": false,
        "emailReceptionCapability": "active"
      },
      "spf": {
        "record": "v=spf1 include:_spf.google.com ~all",
        "valid": true,
        "allPolicy": "~all",
        "totalLookupCount": 3,
        "detectedProviders": ["Google Workspace"]
      },
      "dkim": [
        {
          "selector": "google",
          "valid": true,
          "keyType": "rsa",
          "keySize": 2048
        }
      ],
      "dmarc": {
        "record": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com",
        "valid": true,
        "policy": "reject",
        "rua": ["mailto:dmarc@example.com"]
      },
      "mtaSts": {
        "valid": true,
        "policyMode": "enforce"
      },
      "tlsRpt": {
        "valid": true,
        "rua": ["mailto:tls-reports@example.com"]
      },
      "bimi": {
        "valid": false,
        "errors": ["No BIMI record found"]
      },
      "dnssec": {
        "enabled": true,
        "valid": true
      }
    }
  }
}

Failed Lookups

Any check result can include lookupFailed: true. It means the DNS lookup itself failed (a timeout or a SERVFAIL), so the result says nothing about the record:

"dmarc": {
  "record": null,
  "valid": false,
  "lookupFailed": true,
  "errors": ["..."]
}

Don't treat this as a missing record, and don't publish a new one because of it. MailShield keeps the last stored result for that check, so Get Domain and the score still show the last known state. Try again in a few minutes.

Example

curl -X POST \
  -H "Authorization: Bearer ms_your_token" \
  https://app.mailshield.app/api/v1/domains/550e8400-e29b-41d4-a716-446655440000/checks

Rate Limiting

This endpoint has a stricter rate limit of 5 requests per minute per domain because DNS checks are resource-intensive.

When rate limited, you'll receive a 429 response with a Retry-After header.

TIP

Instead of repeatedly triggering checks, use the Get Domain endpoint to retrieve the latest stored check results.

---

Check Results

Each DNS check returns detailed information about the configuration.

MX Check

{
  "records": [
    {"priority": 10, "exchange": "mail1.example.com"},
    {"priority": 20, "exchange": "mail2.example.com"}
  ],
  "hosts": [
    {
      "hostname": "mail1.example.com",
      "priority": 10,
      "ip": "203.0.113.1",
      "tlsSupported": true,
      "starttlsSupported": true,
      "certificateExpiry": "2025-01-01T00:00:00Z"
    }
  ],
  "tlsSupported": true,
  "daneSupported": false,
  "emailReceptionCapability": "active"
}

Email Reception Capability:

• active: the domain actively receives email
• null-mx: null MX record (RFC 7505)
• no-mail: no MX records
• unreachable: MX hosts not reachable
• unresolvable: MX hosts don't resolve to an address
• relay-denied: the mail servers reject mail for the domain

SPF Check

{
  "record": "v=spf1 include:_spf.google.com ~all",
  "version": "spf1",
  "valid": true,
  "allPolicy": "~all",
  "mechanisms": [...],
  "includeTree": [...],
  "totalLookupCount": 3,
  "flattenedIps": ["172.217.0.0/16", ...],
  "detectedProviders": ["Google Workspace"],
  "errors": [],
  "warnings": ["Consider using -all instead of ~all"]
}

DKIM Check

{
  "selector": "google",
  "record": "v=DKIM1; k=rsa; p=MIIBIjAN...",
  "version": "DKIM1",
  "keyType": "rsa",
  "keySize": 2048,
  "publicKey": "MIIBIjAN...",
  "valid": true,
  "errors": [],
  "warnings": []
}

DMARC Check

{
  "record": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com",
  "version": "DMARC1",
  "policy": "reject",
  "subdomainPolicy": null,
  "percentage": 100,
  "aspf": "r",
  "adkim": "r",
  "rua": ["mailto:dmarc@example.com"],
  "ruf": [],
  "valid": true,
  "errors": [],
  "warnings": []
}

MTA-STS Check

{
  "dnsRecord": "v=STSv1; id=20240115",
  "dnsVersion": "STSv1",
  "dnsId": "20240115",
  "policyFetched": true,
  "policyVersion": "STSv1",
  "policyMode": "enforce",
  "policyMx": ["mail.example.com"],
  "policyMaxAge": 604800,
  "valid": true,
  "errors": []
}

TLS-RPT Check

{
  "record": "v=TLSRPTv1; rua=mailto:tls-reports@example.com",
  "version": "TLSRPTv1",
  "rua": ["mailto:tls-reports@example.com"],
  "valid": true,
  "errors": []
}

BIMI Check

{
  "selector": "default",
  "record": "v=BIMI1; l=https://example.com/logo.svg",
  "version": "BIMI1",
  "location": "https://example.com/logo.svg",
  "authority": null,
  "logoFetched": true,
  "logoValid": true,
  "logoContentType": "image/svg+xml",
  "valid": true,
  "errors": []
}

DNSSEC Check

{
  "enabled": true,
  "valid": true,
  "chainValid": true,
  "dsRecords": [
    {
      "keyTag": 12345,
      "algorithm": 13,
      "digestType": 2,
      "digest": "ABC123..."
    }
  ],
  "errors": []
}