Import the Spaw OpenAPI document into Postman or a generator

Every Spaw endpoint is described in one OpenAPI 3.1 document, which is also the source the reference pages are rendered from, so the two can never disagree. It is served as JSON at https://spaw.co/openapi.json and as YAML at https://spaw.co/openapi.yaml, with no authentication. If your tool understands OpenAPI, it understands Spaw.

What the document contains

The 17 operations cover single and batch verification, the browser endpoint for publishable keys, domain intelligence, the four bulk-job calls, the three suppression-list calls, delivery feedback, the accuracy summary, the provider webhook target, the account endpoint, and the phone and IP endpoints. Each operation carries a request example, a response example, and the named error responses it can return. Three vendor extensions add what a generated client cannot infer: x-spaw-auth says whether the operation takes a bearer key, a publishable key or a feedback key, x-spaw-billing states in one sentence what the operation costs, and x-spaw-errors lists the stable error codes.

The EmailResult schema documents all 27 fields of a verification with their meaning, and the ErrorEnvelope schema is the shape of every failure: { "success": false, "error": { "code", "message", "request_id" } }, with error.errors keyed by field on a validation failure.

Import into an API client

1. Create a secret key on the API keys page.
2. In Postman, choose Import and paste https://spaw.co/openapi.yaml; Postman builds a collection with one request per operation. Insomnia and Bruno both import an OpenAPI URL or file the same way.
3. Set the collection's authorization to bearer token and paste the key. The document declares the bearerAuth scheme on every operation, so the tools apply it automatically.
4. Send the first request against a test address, which costs nothing:

POST https://spaw.co/api/v1/email
{ "email": "[email protected]" }

The six fixed addresses on spaw.test answer canonical verdicts, are never billed, and never appear in your history, so a shared collection can be exercised freely.

Generate a client

Any generator that reads OpenAPI 3.1 works; recent releases of openapi-generator do. For example:

openapi-generator-cli generate \
  -i https://spaw.co/openapi.yaml \
  -g typescript-fetch \
  -o ./spaw-client

Before generating, check whether an official client already exists for your language: Spaw ships hand-written Python, Node.js and PHP clients built from this same document, with the error classes already mapped to the API's codes. A generated client is the right choice for Go, Ruby, Java, C# and everything else.

Use it with AI tools

The document is also the fastest way to teach a coding assistant the API. Point it at https://spaw.co/openapi.yaml, or at https://spaw.co/llms-full.txt, which concatenates every documentation page, the endpoint reference and the verdict reasons into one Markdown file. Each endpoint page under /docs/api/{operationId} has a Markdown twin at the same URL with .md appended.

What to do with the verdict

Whatever the tool, the answer is the same 27-field object. Branch on deliverable: keep deliverable, drop undeliverable, and route risky by reason. The sources array names the dataset and version behind every answer, which is what to quote when a verdict surprises you.

Cost

Importing or generating costs nothing. Lookups follow the usual rules: one credit per fresh deliverable or risky verdict, and nothing for undeliverable verdicts, invalid input, repeats within seven days or the test addresses. Every account gets 10 free lookups a month, and GET /api/v1/account reads the live balance for free.