---
title: "OpenAPI"
description: "The machine-readable reference."
url: "https://nextmail.sh/docs/api/reference/openapi"
area: "API"
category: "Reference"
---

# OpenAPI

The machine-readable reference.

## The document

Served unauthenticated at `/openapi.json`, because a client generator needs it to know how to authenticate, and requiring a key to learn that would be a circle.

**Generate a client**

```
curl -s https://api.nextmail.sh/openapi.json -o openapi.json
openapi-generator generate -i openapi.json -g rust -o ./client
```

The request schemas are derived from the same zod that validates them, so the document cannot describe a field the server would reject. A hand-written spec is a second description of the API that drifts silently, and the failure mode is a generated client sending something the server refuses, which looks like the client's bug.

> TypeScript, Python, Ruby, PHP, Go, Java and C# need no generated client: `@nextmail/sdk`, `nextmail` on PyPI, the `nextmail` gem, `nextmail/sdk` on Packagist, the `nextmail-go` module, `sh.nextmail:nextmail` on Maven Central and `Nextmail` on NuGet wrap every operation, typed, and a parity check holds each of them to this document.

Every operation has an `operationId` named after its SDK method, such as `domains.createAppPassword`, so a generated client names it the way the SDKs do. The document is served with an `ETag` and `Cache-Control: public, max-age=300`, and a request that sends that `ETag` back in `If-None-Match` gets a 304 with no body.