email-dns-health

Email DNS Health

Language

Match user's language: Respond in the same language the user uses.

Overview

A zero-dependency email DNS health checker that uses dig and jq to audit SPF, DKIM, DMARC, BIMI, MTA-STS, and MX records. It detects email providers, counts SPF DNS lookups against the 10-lookup limit, grades overall email health A-F, and provides actionable fix guidance.

Commands

Workflow

Progress:

• Step 1: Run preflight check
• Step 2: Determine command from user request
• Step 3: Execute command via helper script
• Step 4: Present results with actionable guidance
• Step 5: Offer follow-up actions

Step 1: Preflight

Run the helper script to check environment readiness:

bash {SKILL_DIR}/scripts/email-dns-health.sh preflight

Output is JSON. If ready is true, proceed. If false, check the dependencies object — each entry has a status and hint field with specific install instructions. The credentials object shows optional credential status. Use the table below to resolve each failure:

After installing missing dependencies, re-run preflight to confirm ready: true before proceeding.

Step 2: Determine Command

Map the user's request to a command:

Step 3: Execute Command

Run the appropriate command:

bash {SKILL_DIR}/scripts/email-dns-health.sh <command> <args...>

All commands output JSON to stdout. Parse the JSON response.

Step 4: Present Results

Format the JSON output into a human-readable report:

For audit: Present each record type (SPF, DKIM, DMARC, BIMI, MTA-STS, MX) with status indicators, the overall grade, and specific recommendations.

For check-spf: Show the SPF record, DNS lookup count (with breakdown), and warnings if approaching the 10-lookup limit.

For check-dkim: Show key details (algorithm, key length, flags) and security assessment.

For check-dmarc: Show the DMARC policy, reporting addresses, and deployment stage assessment.

For detect-provider: Show detected provider(s) with confidence level.

For setup-guide: Read {SKILL_DIR}/references/provider-configs.md and present the step-by-step guide for the requested provider.

For fix requests: Do NOT call a fix script command — there is none. Instead, this is a Claude-driven workflow: run audit first to get the full health report, then analyze the issues and recommendations. Guide the user through fixes interactively.

Cloudflare automatic fixes: Check preflight's credentials.cloudflare_api_token.status. If "valid", offer to apply DNS changes automatically via the Cloudflare API using curl. If "not_configured", "expired", or "invalid", provide the exact DNS records to add/modify manually. If the user wants automatic fixes, guide them to configure the token:

1. Create a token at https://dash.cloudflare.com/profile/api-tokens with Zone:DNS:Edit permission
2. Save it to ~/.claude/email-dns-health/.env as CLOUDFLARE_API_TOKEN=<token> (see .env.example for format)
3. Re-run preflight to validate the token

Step 5: Follow-up

After presenting results, offer relevant next steps:

• If issues found: offer to guide the user through fixing them (see "For fix requests" in Step 4)
• If SPF lookups high: suggest provider-specific optimizations (read references/best-practices.md)
• If no DMARC: suggest progressive deployment plan
• If DMARC at none: suggest advancing to quarantine
• If non-sending domain detected: suggest null record setup

Degradation

Completion Report

After audit or a fix workflow, present:

[Email DNS Health] Audit Complete

Domain: <domain>
Grade: <A-F>
Score: <score>/120 (core <core>/100 + bonus <bonus>/20)

Core (determines deliverability):
  SPF:    <status> (<lookup_count>/10 lookups)     /30
  DKIM:   <status> (<key_length>-bit <algorithm>)  /30
  DMARC:  <status> (policy: <policy>)              /40

Bonus (nice-to-have):
  BIMI:    <status>                                /10
  MTA-STS: <status>                                /10

MX: <status> (provider: <provider>)

Issues: <count>
Recommendations:
  1. <recommendation>
  2. <recommendation>

Troubleshooting

References

For detailed provider DNS configurations, read {SKILL_DIR}/references/provider-configs.md. For SPF/DKIM/DMARC best practices, read {SKILL_DIR}/references/best-practices.md. For common issues and troubleshooting, read {SKILL_DIR}/references/troubleshooting.md.