Skip to content
Back to search

parse-dmarc

DMARC aggregate report parser with a built-in dashboard. One Go binary, IMAP in, SQLite, Prometheus metrics, MCP server. Apache-2.0.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/dmarcguardhq/parse-dmarc with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/dmarcguardhq/parse-dmarc'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dmarcguardhq--parse-dmarc/badge.svg)](/listings/dmarcguardhq--parse-dmarc)

HTML

<a href="/listings/dmarcguardhq--parse-dmarc"><img src="/api/listings/dmarcguardhq--parse-dmarc/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 211 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Parse DMARC
  2. [![CI](https://img.shields.io/github/actions/workflow/status/dmarcguardhq/parse-dmarc/ci.yml?branch=main&label=CI&style=flat-square)](https://github.com/dmarcguardhq/parse-dmarc/actions/workflows/ci.yml)
  3. [![Release](https://img.shields.io/github/v/release/dmarcguardhq/parse-dmarc?style=flat-square)](https://github.com/dmarcguardhq/parse-dmarc/releases)
  4. [![License](https://img.shields.io/github/license/dmarcguardhq/parse-dmarc?style=flat-square)](LICENSE)
  5. [![Stars](https://img.shields.io/github/stars/dmarcguardhq/parse-dmarc?style=flat-square)](https://github.com/dmarcguardhq/parse-dmarc)
  6. [![Docker pulls old](https://img.shields.io/docker/pulls/meysam81/parse-dmarc?style=flat-square&label=meysam81%2Fparse-dmarc%20%28old%29)](https://hub.docker.com/r/meysam81/parse-dmarc)
  7. [![Docker pulls new](https://img.shields.io/docker/pulls/dmarcguard/parse-dmarc?style=flat-square&label=dmarcguard%2Fparse-dmarc%20%28NEW%29)](https://hub.docker.com/r/dmarcguard/parse-dmarc)
  8. [![Image size](https://img.shields.io/docker/image-size/dmarcguard/parse-dmarc/latest?style=flat-square&label=image)](https://hub.docker.com/r/dmarcguard/parse-dmarc/tags)
  9. <!-- START doctoc generated TOC please keep comment here to allow auto update -->
  10. <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
  11. - [What it does](#what-it-does)
  12. - [Run it](#run-it)
  13. - [Get reports flowing](#get-reports-flowing)
  14. - [Deploy anywhere](#deploy-anywhere)
  15. - [Platform as a Service (PaaS)](#platform-as-a-service-paas)
  16. - [Self-hosted PaaS](#self-hosted-paas)
  17. - [Infrastructure](#infrastructure)
  18. - [Configuration](#configuration)
  19. - [Metrics, Grafana and MCP](#metrics-grafana-and-mcp)
  20. - [Parse DMARC or DMARCguard?](#parse-dmarc-or-dmarcguard)
  21. - [Roadmap and contributing](#roadmap-and-contributing)
  22. - [License](#license)
  23. <!-- END doctoc -->
  24. **Read your DMARC aggregate reports in one dashboard. One Go binary, SQLite, no Elasticsearch.**
  25. Parse DMARC is built and maintained by the team behind [DMARCguard](https://dmarcguard.io/?utm_source=github&utm_medium=referral&utm_campaign=parse-dmarc-readme&utm_content=header), a hosted DMARC monitoring service. The two do not share code, and this repository stays Apache-2.0 in full.
  26. ![Parse DMARC dashboard showing pass rate, message volume and top sending sources](./assets/screenshots/hero.png)
  27. ## What it does
  28. When your DMARC record carries a `rua=` address, mail receivers such as Google, Microsoft and Yahoo send you aggregate reports: gzip or zip XML attachments, usually once a day, listing every IP that sent mail as your domain and whether SPF and DKIM passed ([RFC 7489 section 7.2](https://www.rfc-editor.org/rfc/rfc7489#section-7.2), carried forward by [RFC 9990](https://www.rfc-editor.org/rfc/rfc9990)). Nobody reads those by hand. Parse DMARC does:
  29. - Fetches reports over IMAP from any mailbox, or from a local Maildir when the mail server is on the same host (`MAILDIR_PATH`, see [Configuration](#configuration)). Reports that Exchange or Outlook forward as `message/rfc822` attachments are unwrapped too.
  30. - Parses gzip, zip and raw XML, with a 16 MB decompression cap per report.
  31. - Stores everything in one SQLite file. No database server, no JVM.
  32. - Shows pass rate, message volume and top sending sources, and opens any report down to its raw records.
  33. - Generates your `_dmarc` TXT record from a form.
  34. - Exposes 28 Prometheus metrics and ships a Grafana dashboard.
  35. - Serves an MCP server, so an AI assistant can query your reports.
  36. - Dark mode. One static binary in a minimal container image.
  37. It reads aggregate (RUA) reports only. Failure reports (RUF), TLS-RPT, alerting, login and multi-mailbox intake are not built; see [Roadmap and contributing](#roadmap-and-contributing).
  38. ## Run it
  39. Docker, with a named volume for the database:
  40. ```bash
  41. docker run -d --name parse-dmarc -p 8080:8080 \
  42. -e IMAP_HOST=imap.gmail.com \
  43. -e IMAP_PORT=993 \
  44. -e IMAP_USERNAME=dmarc@example.com \
  45. -e IMAP_PASSWORD='your-app-password' \
  46. -v parse-dmarc:/data \
  47. dmarcguard/parse-dmarc
  48. ```
  49. Homebrew on macOS or Linux:
  50. ```bash
  51. brew install dmarcguardhq/tap/parse-dmarc
  52. parse-dmarc --gen-config # writes a config.json template
  53. parse-dmarc --config config.json
  54. ```
  55. Nix, from our [NUR-style repo](https://github.com/dmarcguardhq/nur):
  56. ```bash
  57. nix profile install github:dmarcguardhq/nur#parse-dmarc # or: nix run github:dmarcguardhq/nur#parse-dmarc
  58. ```
  59. Or download a release archive, `parse-dmarc_<os>_<arch>.tar.gz` (`.zip` on Windows), from the [releases page](https://github.com/dmarcguardhq/parse-dmarc/releases).
  60. Open http://localhost:8080. Gmail needs an [App Password](https://support.google.com/accounts/answer/185833), not the account password. The same image is on Docker Hub as `meysam81/parse-dmarc`; both names track the same builds, and tags such as `v1` or `v1.6.0` pin a release.
  61. ## Get reports flowing
  62. Receivers only send reports if your DMARC record asks for them. Publish this TXT record at `_dmarc.example.com`, with your own domain and mailbox:
  63. ```
  64. v=DMARC1; p=none; rua=mailto:dmarc@example.com
  65. ```
  66. - `p=none` asks receivers to deliver as usual and only report. Move to `p=quarantine`, then `p=reject`, once every legitimate sender in the reports passes ([RFC 9989 section 5.1](https://www.rfc-editor.org/rfc/rfc9989#section-5.1)).
  67. - `rua=` is the mailbox Parse DMARC reads. It has to exist and accept mail before the first report arrives.
  68. - Check the record with `dig +short TXT _dmarc.example.com`. Reports typically start within 24 to 48 hours.
  69. Cloudflare, Route 53 and every other DNS host take the same three fields: name `_dmarc`, type `TXT`, value as above. SPF and DKIM do not have to be set up first; the reports are how you find out what they are doing.
  70. ## Deploy anywhere
  71. One click on a platform, or a template for the self-hosted PaaS you already run. Every option needs the IMAP settings from [Configuration](#configuration).
  72. ### Platform as a Service (PaaS)
  73. | Provider | Deploy | Notes |
  74. | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
  75. | **Railway** | [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/4kqQ_I?referralCode=meysam) | Recommended for beginners |
  76. | **Render** | [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/dmarcguardhq/parse-dmarc) | Free tier available |
  77. | **Koyeb** | [![Deploy to Koyeb](https://www.koyeb.com/static/images/deploy/button.svg)][koyeb-1click] | Global edge deployment. Manually mount `/data` as volume. |
  78. | **Zeabur** | [![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/templates/YB3TS7?referralCode=meysam) | Asia-Pacific optimized |
  79. | **Northflank** | [![Deploy to Northflank](https://assets.northflank.com/deploy_to_northflank_smm_36700fb050.svg)](https://app.northflank.com/s/account/templates/new?data=693e394eb41e1e64db65187e) | Developer-focused |
  80. ### Self-hosted PaaS
  81. | Provider | Deploy | Notes |
  82. | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
  83. | **CapRover** | [![Deploy to CapRover](https://img.shields.io/badge/Deploy-CapRover-0072CE?style=for-the-badge&logo=docker)](./deploy/captain-definition) | Self-hosted PaaS |
  84. | **Coolify** | [![Deploy to Coolify](https://img.shields.io/badge/Deploy-Coolify-6B46C1?style=for-the-badge&logo=docker)](./deploy/coolify.yaml) | Open-source Heroku alternative |
  85. | **Dokploy** | [![Deploy to Dokploy](https://img.shields.io/badge/Deploy-Dokploy-00B4D8?style=for-the-badge&logo=docker)](./deploy/dokploy/) | Self-hosted deployment platform |
  86. | **Docker** | [![Docker](https://img.shields.io/badge/Docker-Pull%20Image-2496ED?style=for-the-badge&logo=docker)](https://hub.docker.com/r/dmarcguard/parse-dmarc) | Run anywhere |
  87. ### Infrastructure
  88. | Provider | Deploy | Notes |
  89. | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
  90. | **DigitalOcean Droplet** | [![Deploy to DigitalOcean](https://img.shields.io/badge/Deploy-DigitalOcean-0080FF?style=for-the-badge&logo=digitalocean)](./deploy/digitalocean/) | VM with Packer image |
  91. ## Configuration
  92. Every setting in this table is an environment variable or a key in `config.json`. Environment is read first and the file overrides it. The command-line flags further down take an environment variable but no `config.json` key.
  93. | Setting | Environment variable | Default |
  94. | ------------------------------ | -------------------------------- | ------------------------------------------------------------ |
  95. | IMAP host and port | `IMAP_HOST`, `IMAP_PORT` | required, `993` |
  96. | IMAP username and password | `IMAP_USERNAME`, `IMAP_PASSWORD` | required |
  97. | Mailbox to read | `IMAP_MAILBOX` | `INBOX` |
  98. | Implicit TLS | `IMAP_USE_TLS` | `true` |
  99. | STARTTLS on a plaintext port | `IMAP_STARTTLS` | `false` |
  100. | Internal CA bundle, PEM | `IMAP_TLS_CA_FILE` | unset |
  101. | Skip certificate verification | `IMAP_TLS_SKIP_VERIFY` | `false` |
  102. | Mark fetched mail as seen | `IMAP_MARK_AS_SEEN` | `true` |
  103. | Move processed mail to | `IMAP_PROCESSED_MAILBOX` | unset |
  104. | Maildir intake instead of IMAP | `MAILDIR_PATH` | unset |
  105. | Maildir deadletter mailbox | `IMAP_DEADLETTER_BOX` | `DEADLETTER` |
  106. | Database file | `DATABASE_PATH` | `~/.parse-dmarc/db.sqlite`, `/data/parse-dmarc.db` in Docker |
  107. | HTTP listen | `SERVER_HOST`, `SERVER_PORT` | `127.0.0.1`, `8080`, `0.0.0.0` in Docker |
  108. | Seconds between fetches | `FETCH_INTERVAL` | `300` |
  109. | Log level | `LOG_LEVEL` | `info` |
  110. The dashboard listens on loopback unless `SERVER_HOST` says otherwise. Set `SERVER_HOST=0.0.0.0` to reach it from another host; the container images already do, since Docker forwards the port to the container's interface rather than its loopback. A `server.host` in the config file overrides `SERVER_HOST`, which is why the sample config leaves the key out.
  111. Providers: Gmail is `imap.gmail.com` on 993 with an App Password. Microsoft 365 is `outlook.office365.com` on 993. Anything else is port 993 with TLS unless its documentation says otherwise.
  112. Note: If using Gmail, to have processed messages moved to the trash, set the `IMAP_PROCESSED_MAILBOX` environment variable to `[Gmail]/Trash`.
  113. An IMAP server whose certificate comes from your own CA fails with `x509: certificate signed by unknown authority`. Mount the CA bundle and point `IMAP_TLS_CA_FILE` at it; verification stays on. `IMAP_TLS_SKIP_VERIFY=true` also connects and is the last resort, because the session can then be intercepted. `IMAP_STARTTLS=true` dials plaintext, usually port 143, and upgrades; it takes precedence over `IMAP_USE_TLS`. Turning TLS off entirely is plaintext IMAP, and most servers refuse `LOGIN` on it.
  114. On a host that already receives the reports, point `MAILDIR_PATH` at the Maildir (for example `/var/mail/dmarc/Maildir`) and no IMAP settings are needed: every fetch reads `<MAILDIR_PATH>/new` and moves each message to `<MAILDIR_PATH>/cur` once it has been parsed. The messages are read as whole emails, exactly as Postfix or Courier deliver them. A message no report can be read from, or whose report does not parse, is moved to `<MAILDIR_PATH>/DEADLETTER` (`IMAP_DEADLETTER_BOX`) instead, so an operator sees what the parser dropped.
  115. | Flag | What it does |
  116. | --------------------------- | --------------------------------------------------------------------------------------------- |
  117. | `--fetch-once` | Fetch, parse, store, exit. For cron. |
  118. | `--serve-only` | Serve the dashboard without fetching. |
  119. | `--fetch-interval 600` | Seconds between fetch cycles. |
  120. | `--metrics=false` | Turn off `/metrics`. |
  121. | `--gen-config` | Write a `config.json` template and exit. |
  122. | `--mcp`, `--mcp-http :8081` | Run the MCP server over stdio or HTTP instead of the fetcher. See [docs/MCP.md](docs/MCP.md). |
  123. ## Metrics, Grafana and MCP
  124. `/metrics` is on by default: 28 metrics covering fetch cycles, IMAP connections, parse and store errors, compliance rate overall and per domain, SPF and DKIM result counts, and HTTP latency. `grafana/dashboard.json` is a ready dashboard for them. The full list, a Prometheus Operator `ServiceMonitor`, alert rules and a compose stack with Prometheus and Grafana are in [docs/METRICS.md](docs/METRICS.md).
  125. `parse-dmarc --mcp` exposes the same data to an AI assistant over the Model Context Protocol: nine tools, from `get_statistics` to `parse_dmarc_report`, over stdio or HTTP with optional OAuth2. Setup and the tool list are in [docs/MCP.md](docs/MCP.md).
  126. The HTTP API behind the dashboard is five `GET` routes: `/api/statistics`, `/api/reports`, `/api/reports/{id}`, `/api/top-sources` and `/api/version`. None of them has authentication, so keep the port behind your reverse proxy or VPN.
  127. To serve the dashboard under a path such as `https://example.com/dmarc/`, have the proxy strip the prefix before forwarding, for example nginx's `location /dmarc/ { proxy_pass http://127.0.0.1:8080/; }` ([full example](contrib/nginx/default.conf)). The dashboard loads its assets and API relative to the page, so it needs no setting of its own.
  128. ## Parse DMARC or DMARCguard?
  129. Two products, one maker, separate codebases. Parse DMARC is the whole of this repository: no enterprise directory, nothing to unlock. DMARCguard is a hosted, proprietary service that reads the reports for you and tells you what to change.
  130. | | Parse DMARC | DMARCguard |
  131. | --------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  132. | Who runs it | You: a binary or container, a mailbox, a volume | We do |
  133. | What it reads | DMARC aggregate reports | DMARC aggregate reports, TLS-RPT reports, failure reports on Pro, and DNS checks for 9 protocols: DMARC, SPF, DKIM, BIMI, MTA-STS, TLS-RPT, ARC, DANE, ARF (7 on Free) |
  134. | Sending sources | IP addresses | 170 named senders, Mailchimp or SendGrid rather than an IP, each with the DNS change that fixes it |
  135. | Alerts | Prometheus rules you write | Email on Free; Slack, Teams, Discord and webhooks on Pro |
  136. | Retention | Whatever your disk holds | 30 days on Free, 1 year on Pro |
  137. | Access control | None; keep it behind your proxy | Accounts and 2FA; SAML SSO on Pro |
  138. | Support | GitHub issues | Email |
  139. | Price | $0, Apache-2.0 | Free for 2 domains, no credit card. Pro is $29/month including 2 domains |
  140. Run Parse DMARC when you want the data on your own disk and one mailbox to watch. Use DMARCguard when you want the reports read for you, or you have more domains than evenings.
  141. > I built Parse DMARC first, in late 2025. DMARCguard came out of what people asked for next: a sender's name instead of its IP, and the exact record to change on every alert. Paying for DMARCguard is what funds the hours that go into this repository, and it stays Apache-2.0.
  142. >
  143. > Meysam
  144. [Start free on 2 domains, no credit card](https://dmarcguard.io/pricing/?utm_source=github&utm_medium=referral&utm_campaign=parse-dmarc-readme&utm_content=which-one)
  145. ## Roadmap and contributing
  146. The most-asked additions, in the order people ask: TLS-RPT reports ([#154](https://github.com/dmarcguardhq/parse-dmarc/issues/154)) and whois on sending sources ([#143](https://github.com/dmarcguardhq/parse-dmarc/issues/143)). Anything else: [open an issue](https://github.com/dmarcguardhq/parse-dmarc/issues/new). [CONTRIBUTING.md](CONTRIBUTING.md) covers the toolchain: `just build`, `just dev`, and `docker compose up` for a local Dovecot seeded with a sample report.
  147. ## License
  148. Apache-2.0, for everything in this repository. There is no `ee/` directory and no feature that needs a key.
  149. ---
  150. If Parse DMARC did the job, a star helps the next person find it. If you would rather have the reports read for you, [DMARCguard](https://dmarcguard.io/?utm_source=github&utm_medium=referral&utm_campaign=parse-dmarc-readme&utm_content=footer) is the hosted product from the same team.
  151. [koyeb-1click]: https://app.koyeb.com/deploy?name=parse-dmarc&type=docker&image=docker.io%2Fdmarcguard%2Fparse-dmarc%3Alatest&regions=fra&env%5BDATABASE_PATH%5D=%2Fdata%2Fdb.sqlite&env%5BIMAP_HOST%5D=&env%5BIMAP_MAILBOX%5D=INBOX&env%5BIMAP_PASSWORD%5D=&env%5BIMAP_PORT%5D=993&env%5BIMAP_USERNAME%5D=&env%5BIMAP_USE_TLS%5D=true&env%5BSERVER_PORT%5D=8080&ports=8080%3Bhttp%3B%2F&hc_protocol%5B8080%5D=http&hc_grace_period%5B8080%5D=5&hc_interval%5B8080%5D=30&hc_restart_limit%5B8080%5D=3&hc_timeout%5B8080%5D=5&hc_path%5B8080%5D=%2Fapi%2Fstatistics&hc_method%5B8080%5D=get

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.