# SPF builder API

Build an SPF record from the services that send your mail, or check one you already have, with its lookup count.

`POST /v1/build/spf`

- Price: Free; any API key works and nothing is charged.
- Cache: Never cached; every call runs again.
- MCP tool: `build_dns_record`

An SPF record built from your senders, or a pasted record checked, with its DNS lookup count and the include tree. Free; any API key works and nothing is charged. Never cached; every call runs again.

## Request body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string or null | no | Your domain; needed for the mx and a mechanisms and to count lookups. |
| `record` | string or null | no | An existing SPF record to check instead of building one. |
| `providers` | array of string or null | no | Mail services that send for your domain. |
| `includes` | array of string or null | no | Other include domains, one per line. |
| `ip4` | array of string or null | no | IPv4 addresses or ranges that send mail, one per line. |
| `ip6` | array of string or null | no | IPv6 addresses or ranges that send mail, one per line. |
| `a` | boolean or null | no | The domain's own web server sends mail. |
| `mx` | boolean or null | no | The domain's mail servers also send mail. |
| `all` | "-all" | "~all" | no | What receivers do with mail from anyone else. |

## Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tool` | string | yes |  |
| `target` | string | yes |  |
| `status` | "ok" | "partial" | "error" | yes |  |
| `fetched_at` | string | no |  |
| `cached` | boolean | no |  |
| `credits_used` | integer | no | Credits this call took from your balance. 0 for free tools, for a replay of an earlier call, and for a free check run on the website without signing in |
| `summary` | string | yes |  |
| `score` | integer or null | no |  |
| `findings` | array of object | no |  |
| `credits_remaining` | integer | yes | Your balance after this call. It can be below zero after a refund; free tools still work then |
| `data` | object | yes | This tool's result |
| `data.kind` | "spf" | "dmarc" | "caa" | yes |  |
| `data.name` | string | yes |  |
| `data.type` | "TXT" | "CAA" | yes |  |
| `data.value` | string | yes |  |
| `data.strings` | array of string | yes |  |
| `data.length` | integer | yes |  |
| `data.zone_line` | string | yes |  |
| `data.mode` | "build" | "validate" | yes |  |
| `data.spf` | object or null | no |  |
| `data.dmarc` | object or null | no |  |
| `data.caa` | object or null | no |  |

## Errors

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

## Example

```sh
curl -X POST "https://api.dnssuper.com/v1/build/spf" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'
```

```python
import os

import httpx

client = httpx.Client(
    base_url="https://api.dnssuper.com",
    headers={"Authorization": f"Bearer {os.environ['DNSSUPER_API_KEY']}"},
    timeout=60,
)
response = client.post("/v1/build/spf", json={
    "domain": "example.com",
})
response.raise_for_status()
result = response.json()
print(result["summary"], result["credits_used"])
```

```ts
const response = await fetch("https://api.dnssuper.com/v1/build/spf", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"domain":"example.com"}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result.summary, result.credits_used);
```

Example response:

```json
{
  "tool": "spf-generator",
  "target": "",
  "status": "ok",
  "fetched_at": "2026-11-14T10:00:00Z",
  "cached": false,
  "credits_used": 0,
  "summary": "Your SPF record is ready to publish as a TXT record. It needs 6 of the 10 DNS lookups receivers allow.",
  "findings": [
    {
      "id": "spf_builder.softfail",
      "severity": "info",
      "title": "This record ends in ~all",
      "detail": "",
      "fix": "Move to -all once DMARC reports show all your mail passes."
    }
  ],
  "data": {
    "kind": "spf",
    "name": "example.com",
    "type": "TXT",
    "value": "v=spf1 mx include:_spf.google.com include:sendgrid.net ~all",
    "strings": [
      "v=spf1 mx include:_spf.google.com include:sendgrid.net ~all"
    ],
    "length": 59,
    "zone_line": "example.com. 3600 IN TXT \"v=spf1 mx include:_spf.google.com include:sendgrid.net ~all\"",
    "mode": "build",
    "spf": {
      "lookups": 6,
      "lookup_limit": 10,
      "void_lookups": 0,
      "capped": false,
      "tree": {
        "domain": "example.com",
        "status": "given",
        "record": "v=spf1 mx include:_spf.google.com include:sendgrid.net ~all",
        "errors": [],
        "terms": [
          {
            "term": "mx",
            "mechanism": "mx",
            "qualifier": "+",
            "target": "example.com",
            "counted": true,
            "status": "ok",
            "addresses": [
              "93.184.215.20"
            ],
            "hosts": [
              "mx1.example.com"
            ],
            "detail": ""
          },
          {
            "term": "include:_spf.google.com",
            "mechanism": "include",
            "qualifier": "+",
            "target": "_spf.google.com",
            "counted": true,
            "status": "ok",
            "addresses": [],
            "hosts": [],
            "detail": "",
            "child": {
              "domain": "_spf.google.com",
              "status": "found",
              "record": "v=spf1 include:_netblocks.google.com include:_netblocks2.google.com include:_netblocks3.google.com ~all",
              "errors": [],
              "terms": [
                {
                  "term": "include:_netblocks.google.com",
                  "mechanism": "include",
                  "qualifier": "+",
                  "target": "_netblocks.google.com",
                  "counted": true,
                  "status": "ok",
                  "addresses": [],
                  "hosts": [],
                  "detail": "",
                  "child": {
                    "domain": "_netblocks.google.com",
                    "status": "found",
                    "record": "v=spf1 ip4:35.190.247.0/24 ip4:64.233.160.0/19 ip4:66.102.0.0/20 ip4:66.249.80.0/20 ip4:72.14.192.0/18 ~all",
                    "errors": [],
                    "terms": [
                      {
                        "term": "ip4:35.190.247.0/24",
                        "mechanism": "ip4",
                        "qualifier": "+",
                        "target": "35.190.247.0",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      },
                      {
                        "term": "ip4:64.233.160.0/19",
                        "mechanism": "ip4",
                        "qualifier": "+",
                        "target": "64.233.160.0",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      },
                      {
                        "term": "ip4:66.102.0.0/20",
                        "mechanism": "ip4",
                        "qualifier": "+",
                        "target": "66.102.0.0",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      },
                      {
                        "term": "ip4:66.249.80.0/20",
                        "mechanism": "ip4",
                        "qualifier": "+",
                        "target": "66.249.80.0",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      },
                      {
                        "term": "ip4:72.14.192.0/18",
                        "mechanism": "ip4",
                        "qualifier": "+",
                        "target": "72.14.192.0",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      },
                      {
                        "term": "~all",
                        "mechanism": "all",
                        "qualifier": "~",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      }
                    ]
                  }
                },
                {
                  "term": "include:_netblocks2.google.com",
                  "mechanism": "include",
                  "qualifier": "+",
                  "target": "_netblocks2.google.com",
                  "counted": true,
                  "status": "ok",
                  "addresses": [],
                  "hosts": [],
                  "detail": "",
                  "child": {
                    "domain": "_netblocks2.google.com",
                    "status": "found",
                    "record": "v=spf1 ip6:2001:4860:4000::/36 ip6:2404:6800:4000::/36 ip6:2607:f8b0:4000::/36 ~all",
                    "errors": [],
                    "terms": [
                      {
                        "term": "ip6:2001:4860:4000::/36",
                        "mechanism": "ip6",
                        "qualifier": "+",
                        "target": "2001:4860:4000::",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      },
                      {
                        "term": "ip6:2404:6800:4000::/36",
                        "mechanism": "ip6",
                        "qualifier": "+",
                        "target": "2404:6800:4000::",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      },
                      {
                        "term": "ip6:2607:f8b0:4000::/36",
                        "mechanism": "ip6",
                        "qualifier": "+",
                        "target": "2607:f8b0:4000::",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      },
                      {
                        "term": "~all",
                        "mechanism": "all",
                        "qualifier": "~",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      }
                    ]
                  }
                },
                {
                  "term": "include:_netblocks3.google.com",
                  "mechanism": "include",
                  "qualifier": "+",
                  "target": "_netblocks3.google.com",
                  "counted": true,
                  "status": "ok",
                  "addresses": [],
                  "hosts": [],
                  "detail": "",
                  "child": {
                    "domain": "_netblocks3.google.com",
                    "status": "found",
                    "record": "v=spf1 ip4:172.217.0.0/19 ip4:172.217.32.0/20 ip4:108.177.96.0/19 ~all",
                    "errors": [],
                    "terms": [
                      {
                        "term": "ip4:172.217.0.0/19",
                        "mechanism": "ip4",
                        "qualifier": "+",
                        "target": "172.217.0.0",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      },
                      {
                        "term": "ip4:172.217.32.0/20",
                        "mechanism": "ip4",
                        "qualifier": "+",
                        "target": "172.217.32.0",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      },
                      {
                        "term": "ip4:108.177.96.0/19",
                        "mechanism": "ip4",
                        "qualifier": "+",
                        "target": "108.177.96.0",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      },
                      {
                        "term": "~all",
                        "mechanism": "all",
                        "qualifier": "~",
                        "counted": false,
                        "status": "ok",
                        "addresses": [],
                        "hosts": [],
                        "detail": ""
                      }
                    ]
                  }
                },
                {
                  "term": "~all",
                  "mechanism": "all",
                  "qualifier": "~",
                  "counted": false,
                  "status": "ok",
                  "addresses": [],
                  "hosts": [],
                  "detail": ""
                }
              ]
            }
          },
          {
            "term": "include:sendgrid.net",
            "mechanism": "include",
            "qualifier": "+",
            "target": "sendgrid.net",
            "counted": true,
            "status": "ok",
            "addresses": [],
            "hosts": [],
            "detail": "",
            "child": {
              "domain": "sendgrid.net",
              "status": "found",
              "record": "v=spf1 ip4:167.89.0.0/17 ip4:208.117.48.0/20 ~all",
              "errors": [],
              "terms": [
                {
                  "term": "ip4:167.89.0.0/17",
                  "mechanism": "ip4",
                  "qualifier": "+",
                  "target": "167.89.0.0",
                  "counted": false,
                  "status": "ok",
                  "addresses": [],
                  "hosts": [],
                  "detail": ""
                },
                {
                  "term": "ip4:208.117.48.0/20",
                  "mechanism": "ip4",
                  "qualifier": "+",
                  "target": "208.117.48.0",
                  "counted": false,
                  "status": "ok",
                  "addresses": [],
                  "hosts": [],
                  "detail": ""
                },
                {
                  "term": "~all",
                  "mechanism": "all",
                  "qualifier": "~",
                  "counted": false,
                  "status": "ok",
                  "addresses": [],
                  "hosts": [],
                  "detail": ""
                }
              ]
            }
          },
          {
            "term": "~all",
            "mechanism": "all",
            "qualifier": "~",
            "counted": false,
            "status": "ok",
            "addresses": [],
            "hosts": [],
            "detail": ""
          }
        ]
      },
      "flattening": {
        "needed": false,
        "advice": ""
      }
    }
  },
  "credits_remaining": 498
}
```

## MCP

```json
{
  "tool": "build_dns_record",
  "arguments": {
    "domain": "example.com"
  }
}
```

```text
Your SPF record is ready to publish as a TXT record. It needs 6 of the 10 DNS lookups receivers allow.
Name: example.com (TXT)
Value: v=spf1 mx include:_spf.google.com include:sendgrid.net ~all
Lookups: 6 of 10
Zone line: example.com. 3600 IN TXT "v=spf1 mx include:_spf.google.com include:sendgrid.net ~all"
- info: This record ends in ~all
Free | checked 2026-11-14 10:00 UTC
```
