# SPF Flattener and Lookup Limit Fixer

Propose fixes for an SPF record that is over, or at, the limit of 10 DNS lookups (RFC 7208). Reads the published record (or a pasted v=spf1 record), builds the include tree with the lookups each part costs, the addresses it adds and the provider, and ranks the fixes: replace mx with addresses, split senders onto a subdomain, flatten includes into addresses (never for macro or exists includes), remove what is unused. Returns the cost table, the suggestions with the lookups saved and how risky each is (flattening goes stale when a provider changes its addresses), and the new TXT record or records to publish, split into 255 byte strings, at most 6 records. keep names are never flattened. Nothing is changed for you.

**Not for:** Checking one SPF record (use spf_check) or building one from scratch (use the SPF generator).

- Tool id: `spf-optimize`
- Category: email
- Execution: fanout
- MCP tool `spf_optimize` at https://lookupowl.com/mcp
- REST `GET https://lookupowl.com/api/v1/tools/spf-optimize` (or POST a JSON body)
- OpenAPI: https://lookupowl.com/api/openapi.json

## Input

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `domain` | string | yes |  | The domain whose SPF record to fix, such as example.com. min length 1, max length 253 |
| `keep` | string[] | no |  | Names (includes) that must be kept as they are and never flattened, for example a provider that changes its addresses often. max 30 items |
| `maxLookups` | integer | no | `9` | The number of lookups to aim for. 9 leaves one spare so adding a sender later does not break the record. min 1, max 10 |
| `record` | string | no |  | Try a record before you publish it: a v=spf1 record to fix instead of the one published for the domain. max length 4096 |
| `choose` | string[] | no |  | Ids of the fixes to apply (remove-unused, remove-redundant, replace-mx, subdomain-split, flatten). They are applied in that order. Without it the plan uses the safe ones, and the others only as far as needed to reach the target. Flatten is never in the default plan. max 10 items |
| `flattened` | string[] | no |  | Includes that were flattened earlier. On a recheck, their addresses today are compared with what the domain's own records cover, and any address they list now that is not covered is reported in drift. max 10 items |

## Output

Results are wrapped in an envelope: `tool`, `version`, `requestId`, `data`, `summary`, `meta` (cache status, timing), `permalink`. `data` has these fields:

| Field | Type | Description |
|---|---|---|
| `domain` | string |  |
| `source` | "published" \| "pasted" |  |
| `state` | "no-record" \| "multiple" \| "fine" \| "at-limit" \| "over" | no-record: nothing to optimize. multiple: several SPF records (merge them first). fine: at or under the target. at-limit: valid but above the target or with no lookup to spare. over: more than 10 lookups, which receivers read as an error. |
| `before` | object |  |
| `costTable` | object[] |  |
| `suggestions` | object[] |  |
| `plan` | object |  |
| `flatten` | object | What flattening the suggested includes would cost: records to publish, total bytes, merged address blocks. tooBig: more than 6 records. |
| `noSafeFix` | boolean | No fix other than flattening gets the record to the target. |
| `drift` | object[] | On a recheck: what changed in a flattened include since the plan was made. |
| `issues` | any[] |  |
| `warnings` | string[] |  |
| `permalink` | string | The address of this check (the domain, and the includes flattened when the plan flattens). Never the pasted record. |

## Examples

### At the limit: github.com

```json
{"domain":"github.com","maxLookups":9}
```

```bash
curl 'https://lookupowl.com/api/v1/tools/spf-optimize?domain=github.com&maxLookups=9'
```

Web page: https://lookupowl.com/spf-flattener?q=github.com

### Nothing to fix: example.com

```json
{"domain":"example.com","maxLookups":9}
```

```bash
curl 'https://lookupowl.com/api/v1/tools/spf-optimize?domain=example.com&maxLookups=9'
```

Web page: https://lookupowl.com/spf-flattener?q=example.com

### Try a record before you publish it

```json
{"domain":"brandco.com","maxLookups":9,"record":"v=spf1 mx include:_spf.google.com include:spf.protection.outlook.com include:servers.mcsv.net include:mktomail.com include:mail.zendesk.com include:sendgrid.net include:_spf.salesforce.com include:amazonses.com ~all"}
```

```bash
curl 'https://lookupowl.com/api/v1/tools/spf-optimize?domain=brandco.com&maxLookups=9&record=v%3Dspf1+mx+include%3A_spf.google.com+include%3Aspf.protection.outlook.com+include%3Aservers.mcsv.net+include%3Amktomail.com+include%3Amail.zendesk.com+include%3Asendgrid.net+include%3A_spf.salesforce.com+include%3Aamazonses.com+%7Eall'
```

Web page: https://lookupowl.com/spf-flattener?q=brandco.com&record=v%3Dspf1+mx+include%3A_spf.google.com+include%3Aspf.protection.outlook.com+include%3Aservers.mcsv.net+include%3Amktomail.com+include%3Amail.zendesk.com+include%3Asendgrid.net+include%3A_spf.salesforce.com+include%3Aamazonses.com+%7Eall

## Web pages

- https://lookupowl.com/spf-flattener

## Limits and caching

- Cost: 12 units for a live lookup, 1 unit for a cached one. Budgets are per network and published in the `RateLimit` response headers.
- Cache: results are kept for 300 s. Add `fresh=true` (MCP argument or query parameter) to look again; it costs 3 units per unit and is limited to 10 per hour.
- Timeout: 20 s.

## Related tools

- [SPF Record Checker](https://lookupowl.com/tools/spf-checker.md): Check a domain's SPF record, count its DNS lookups against the limit of 10 and find errors.
- [SPF Record Generator](https://lookupowl.com/tools/spf-generator.md): Build a valid SPF record from your mail providers and IP addresses, with a lookup-limit check.
- [DMARC Record Checker](https://lookupowl.com/tools/dmarc-checker.md): Look up and validate a domain's DMARC policy, report addresses and alignment settings.
- [DKIM Record Checker](https://lookupowl.com/tools/dkim-checker.md): Find and check a domain's DKIM public keys, even when you do not know the selector.
- [Email Health Checker and Spoofing Test](https://lookupowl.com/tools/email-health.md): Check a domain's whole mail setup in one report: mail servers, SPF, DKIM, DMARC, BIMI, MTA-STS, TLS-RPT and blocklists, with the fixes to make first.
- [DNS Lookup](https://lookupowl.com/tools/dns-lookup.md): Look up A, AAAA, MX, NS, TXT, CNAME, SOA, CAA, DS and DNSKEY records from a public resolver or the authoritative nameserver.

## Guide: SPF flattener and lookup fixer

Get an SPF record under the limit of 10 DNS lookups, with the safest fixes first and the new records ready to publish.

### The 10 lookup limit, and what counts

SPF lets a receiver make at most 10 DNS lookups while it checks one message. Every `include`, `a`, `mx`, `ptr`, `exists` and `redirect` costs one, and so does every one of those inside an include. Plain `ip4` and `ip6` addresses cost nothing. Go over the limit and the record returns a permanent error (RFC 7208), so receivers may treat your mail as unauthenticated.

The limit is easy to reach. A company that uses Google Workspace, a marketing tool, a help desk and a billing service can hit it with four includes, because each provider's own record has includes inside. The checker follows the whole tree and shows what each include costs, so you can see where the lookups go before you change anything.

### How to fix a record

1. **Enter the domain**: We read its published SPF record and every include under it. To try a change first, paste a `v=spf1` record under "Try a record before you publish it" and we count that one instead.
2. **Look at the budget bar**: The bar shows each include as a block against the limit of 10 and a tick at your target. The default target is 9, which leaves one spare so adding a sender later does not break the record.
3. **Follow the ladder**: The fixes are in order, safest first. Tick or clear Apply on a step and the plan, the count and the records are rebuilt. Without JavaScript you see the recommended plan.
4. **Publish in order**: Publish any new records first, then change the root record, then check it with the [SPF checker](https://lookupowl.com/spf-record-checker).

> **In Claude, ChatGPT or Cursor** Connect the LookupOwl MCP server and ask: "My SPF record for example.com has too many lookups. What should I change?" The assistant calls `spf_optimize` and gets the same plan.

### The fixes, in the order we offer them

| Fix | What it does | Risk |
|---|---|---|
| Remove dead includes | Drops includes that no longer have an SPF record. More than 2 empty answers is an error of its own. | Safe |
| Drop repeats and ptr | Removes an include listed twice and the discouraged ptr term. | Safe |
| Replace mx with addresses | Swaps the mx term for the addresses of your mail servers. Saves one lookup. | You must confirm the addresses are fixed |
| Move senders to a subdomain | Gives marketing senders their own record on a subdomain such as news.example.com. | You must confirm, and check alignment there |
| Flatten includes | Copies a provider's addresses into your record, so it needs no lookup. | Goes stale when the provider changes |

The default plan applies the safe steps, then only as many of the others as it takes to reach your target. Flattening is never in the default plan. An include that uses a macro or `exists` depends on the sender and can never be copied, so those are marked and left alone, and any name you list under "Keep these includes as they are" is never flattened.

### Why flattening is the last resort

A flattened record is a snapshot. When a provider adds or moves a sending address, your copy is wrong until you update it, and mail from the new address can fail SPF. The ladder marks flattening as going stale, shows how much bigger the record becomes, and offers it as a plan only when it fits in 6 records. An include we have never seen change is labelled "No history yet" and is never pre-selected.

If you flatten anyway, keep a reminder to recheck. A recheck link carries the names of the includes you flattened, and the page then compares their addresses today with what your records cover and lists any that are missing. For a record you have not published yet, the same page works as a calculator.

### Other checks that go with SPF

- Start from your list of senders with the [SPF record generator](https://lookupowl.com/spf-record-generator).
- Check DKIM, which carries mail that SPF cannot, with the [DKIM checker](https://lookupowl.com/dkim-checker).
- See whether your policy protects the domain with the [DMARC checker](https://lookupowl.com/dmarc-checker).
- Run the bulk sender rules of Gmail and Yahoo with the [sender requirements check](https://lookupowl.com/gmail-yahoo-sender-requirements).

### Frequently asked questions

**What happens when SPF needs more than 10 lookups?**

The receiver stops and returns a permanent error. Many treat the message as if SPF had failed, and some reject it. The error is silent for the sender, so mail simply starts failing.

**Should I always flatten my SPF record?**

No. Flattening works but goes stale when providers change their addresses. Remove what is dead, move marketing senders to a subdomain and ask providers for a single include first. Flatten only what is left.

**Why is my target 9 and not 10?**

At exactly 10 lookups the next include you add breaks the record. A target of 9 leaves a spare. You can change it under More options.

**Why can some includes not be flattened?**

An include that uses a macro or `exists` is judged per message, from the sender address, so it has no fixed list of addresses to copy. The same goes for `ptr` and for names that did not answer.

**Does the tool change my DNS?**

No. It reads your records and writes the new ones as text for you to publish. Nothing is changed for you, and a record you paste is counted but never stored or put in the page address.

**How big can a flattened record be?**

One TXT string holds 255 characters, and a record is split into several strings that DNS joins. Large flattened lists are split across up to 6 records here. Above that, moving senders to a subdomain is the better route.
