SPF tells receivers which servers may send mail for your domain. Every third-party service you add — Google Workspace, Microsoft 365, a newsletter tool, a helpdesk — usually adds an include, and each include can contain more includes. At some point the record crosses the limit of 10 DNS lookups and SPF breaks for everyone.
The SPF Flattener follows the whole chain, counts lookups exactly as RFC 7208 does, draws the tree, and generates a flattened record that keeps the original evaluation order and qualifiers.
What is an SPF flattener?
In simple terms
Flattening replaces DNS-querying mechanisms (include, a, mx, redirect) with the IP addresses they currently stand for, so receivers need fewer lookups.
Technical background
SPF evaluation (RFC 7208 §4.6) runs through the terms in order; the first mechanism that matches the sending IP decides the result with its qualifier: + Pass, - Fail, ~ SoftFail, ? Neutral. Six terms query DNS and count towards the limit of 10 (§4.6.4): include, a, mx, ptr, exists and the redirect modifier. ip4, ip6 and all cost nothing. The exp modifier is only looked up after a Fail, to build the rejection text, and does not count. The count is cumulative across nested includes and redirects.
Void lookups are DNS queries that return NXDOMAIN or no data. More than two cause PermError, too.
An include is not a text import. include:X matches only when evaluating X returns Pass; then the include's own qualifier applies. A redirect= is different again: it is used only when nothing else in the record matched, and then the target record decides the result on its own.
Why use an SPF flattener?
- Fix “SPF PermError: too many DNS lookups” without removing services.
- See which include consumes most of the budget.
- Find broken includes, void lookups, loops and duplicate records.
- Test a proposed record before publishing it.
Who should use it?
Mail administrators and DNS managers for domains with several sending services, consultants auditing email authentication, and anyone whose DMARC reports show SPF PermError.
How the SPF flattener works
The NetTools server resolves only what SPF evaluation needs: TXT, A, AAAA and MX records, for names taken from the records. It uses public resolvers, with limits on queries, nesting depth and time, and a TTL-based cache. Your browser then builds the lookup tree and the flattened record.
For each included record, the tool computes the exact set of addresses that would pass. It walks the record in order:
- An address that an earlier
-,~or?term matches is decided there, and never passes through a later term. - A redirect target is used only for addresses that nothing else matched.
The root record is then rewritten term by term, in the original order:
q include:Xbecomesq ip4/ip6for exactly X's pass set.aandmxbecome their addresses, with the same prefix lengths.redirect=becomes the target's terms appended at the end.
Optional clean-ups never change the result. Ranges already decided by an earlier term are removed, and consecutive ranges with the same qualifier are merged into the minimal exact CIDR list.
A built-in semantic check then evaluates both records for hundreds of sample addresses and reports any difference.
How to use the NetTools.tech SPF Flattener
- Open the SPF Flattener and enter a domain, or paste a custom record under Advanced settings.
- Press Resolve & flatten and read the lookup counter: 0–8 is fine, 9–10 is near the limit, above 10 is a PermError risk.
- Explore the lookup tree. Σ shows the running count in evaluation order, and red markers show terms past the 10th lookup.
- Review the flattened record, its status (fully or partly flattened), the semantic check and the differences list.
- If the record is long, use the split version, which moves ranges into
_spf1.<domain>include records. - Copy the record, or export the analysis as PDF, CSV or JSON.
Understanding the results
- Lookup counts: shown as the worst case, with every DNS-querying term evaluated. A message that matches an earlier term needs fewer lookups, so the count for an individual email can be lower.
- Fully flattened: no DNS-querying terms remain.
- Partly flattened: some terms were kept unchanged, for example:
- sender-dependent macros such as
%{i}or%{l}; ptr;- includes whose result depends on the message;
- broken includes, kept so their PermError remains visible.
- sender-dependent macros such as
- Record size: a TXT string holds at most 255 octets, so long records are split into several strings in one TXT record. Answers above about 512 bytes need EDNS or TCP.
Example: Google Workspace, Microsoft 365 and a newsletter tool
A record with include:_spf.google.com include:spf.protection.outlook.com include:servers.mcsv.net mx -all might need 9 lookups: three nested for Google, two for Microsoft, one for Mailchimp, and the mx. Flattening replaces all of them with ip4 and ip6 ranges and keeps -all at the end. The result is 0 lookups, but around 30 ranges and 600 characters, so the split version with two include records (2 lookups) is the practical choice.
Common use cases
- Recovering from SPF PermError after adding a new sending service.
- Checking a provider's record before adding its include.
- Comparing the published record with a proposed one.
- Documenting the authorised sending infrastructure for an audit.
Troubleshooting
Multiple SPF records
Publishing two v=spf1 records is a PermError for every message. Merge them into one record.
An include points to a domain without an SPF record
This is a PermError when the include is reached. The flattener keeps the term so the error stays visible. Remove the include or correct the name.
DNS errors
Timeouts and SERVFAIL are temporary errors. Affected terms are kept unflattened. Run the analysis again later.
“Partly flattened”
Read the “Kept unchanged” list. Macros and ptr depend on the message and cannot be turned into addresses.
Common mistakes
- Copying every IP from every include before
-all, which ignores include semantics and negative qualifiers. - Forgetting to update the flattened record when a provider adds new ranges.
- Treating
redirect=likeinclude— redirect replaces the whole result. - Using
ptr, which is deprecated in RFC 7208 §5.5: it is slow and some receivers ignore it. - Expecting SPF macros to bypass the lookup limit — they still cost lookups.
Limitations
The analysis is a snapshot of today's DNS. Lookup counts are worst-case totals across all branches. TTLs are shown for A and AAAA answers; the resolver library does not report them for TXT and MX. The server resolves at most 150 DNS queries and 12 nesting levels per analysis.
Security & privacy
Only domain names are accepted. The server makes only TXT, A, AAAA and MX queries, for names that appear in the SPF records, through public resolvers (1.1.1.1, 8.8.8.8), with rate limits and timeouts. Results are not stored. NetTools never publishes or changes DNS records.
Related tools
- SPF Lookup — check the published record and its lookup count.
- SPF Record Generator — build a new record from your services.
- DMARC Checker — the policy that uses SPF results.
- Email Deliverability Checker — the full mail setup.
- DMARC Aggregate Report Analyzer — see whether SPF passes in practice.
Summary
Flattening removes DNS lookups by replacing mechanisms with the addresses they stand for. Done correctly, it preserves include semantics, qualifiers, order and redirect fallback. The NetTools.tech SPF Flattener builds the record that way, checks it against the original, and lists every remaining difference. It also reminds you that a flattened record is a snapshot that must be kept up to date.
Frequently asked questions
What does “SPF PermError: too many DNS lookups” mean?
Evaluating the record needs more than 10 DNS-querying terms (include, a, mx, ptr, exists, redirect), counted across all nested includes. Receivers stop and return PermError, so SPF fails for mail that did not match earlier.
Is a flattened record equivalent to the original?
For addresses the analysis can resolve, yes, if it is built correctly: each include is replaced by exactly the addresses it would pass, in the same position and with the same qualifier. Terms that depend on the message, such as macros and ptr, cannot be replaced by a static list.
Why can’t I just list every IP address from every include?
Includes match only when the included record returns Pass, and their qualifier decides the result. An address that an included record fails, or one under a -include, would wrongly become a pass.
What is a void lookup?
A DNS lookup made for SPF that returns NXDOMAIN or no records. RFC 7208 recommends a PermError after more than two of them.
How often should I regenerate a flattened record?
Whenever a provider changes its addresses — which you are not told about. Re-check at least weekly, and daily if the source records have short TTLs.
Does splitting the record into several DNS names avoid the limit?
No. Every include that is evaluated still counts. Subdomains help only when a mail stream really uses a different domain in the envelope sender.