{
  "openapi": "3.1.1",
  "info": {
    "title": "NeatMail public HTTP surface",
    "version": "2026-08-23",
    "summary": "Machine-readable description of www.neatmail.app and NeatMail's OAuth scopes.",
    "description": "NeatMail is an AI email assistant for Gmail and Outlook. This document describes the\nendpoints of the NeatMail marketing site that agents can call, the machine-readable files\nit publishes, and the named OAuth 2.0 scopes NeatMail uses.\n\nThere is no general-purpose NeatMail developer API yet. Everything under\n`https://dashboard.neatmail.app/api` other than the health endpoint below is first-party and requires an\nauthenticated NeatMail session, so it is not described here.\n\nThe security schemes are declared for discoverability of scopes:\n`neatmailOAuth` is the authorization server that signs users into NeatMail;\n`googleGmailOAuth` and `microsoftGraphOAuth` are the delegated grants NeatMail asks a user\nto make to their own mail provider. None of the endpoints in `paths` requires any of them.\n\nEvery HTML page on this site also serves `text/markdown` by content negotiation — see\nthe `/{page}` operation.\n\nVersioning is in the URL path (`/api/v1`). Deprecated paths keep working and\nannounce themselves with RFC 9745 `Deprecation`, RFC 8594 `Sunset` and a\n`successor-version` link, with at least 6 months' notice.\n\nEvery 4xx and 5xx is an RFC 9457 `application/problem+json` document with a stable\nmachine-readable `code` — see the `Problem` schema.",
    "contact": {
      "name": "NeatMail support",
      "email": "help@send.neatmail.app",
      "url": "https://www.neatmail.app/developers"
    },
    "license": {
      "name": "Elastic License 2.0",
      "url": "https://github.com/Lakshay1509/NeatMail/blob/main/LICENSE"
    },
    "termsOfService": "https://www.neatmail.app/terms-and-conditions"
  },
  "externalDocs": {
    "description": "NeatMail developer resources",
    "url": "https://www.neatmail.app/developers"
  },
  "servers": [
    {
      "url": "https://www.neatmail.app",
      "description": "NeatMail marketing site"
    }
  ],
  "security": [],
  "paths": {
    "/{page}": {
      "get": {
        "operationId": "getPage",
        "summary": "Fetch any site page as HTML or Markdown",
        "description": "Every page listed in /sitemap.xml is available at the same URL in two representations. Send `Accept: text/markdown` for the Markdown variant; anything else, including a browser's `Accept`, returns HTML. Responses carry `Vary: Accept`.",
        "parameters": [
          {
            "name": "page",
            "in": "path",
            "required": true,
            "description": "Site path without the leading slash, e.g. `pricing` or `blog/inbox-zero-100-emails-a-day`.",
            "schema": {
              "type": "string"
            },
            "example": "pricing"
          },
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Requested representation.",
            "schema": {
              "type": "string",
              "enum": [
                "text/html",
                "text/markdown",
                "text/x-markdown",
                "text/plain"
              ],
              "default": "text/html"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page, in the negotiated representation.",
            "headers": {
              "Vary": {
                "description": "Always includes `Accept`.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such page. The body is a short Markdown document pointing at the sitemap, llms.txt and developer resources.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "406": {
            "description": "No offered representation matched the `Accept` header. A client that accepts JSON receives an RFC 9457 problem document; anything else gets the same information as plain text.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://www.neatmail.app/developers#error-not-acceptable",
                  "title": "No acceptable representation",
                  "status": 406,
                  "detail": "No acceptable representation",
                  "instance": "/pricing",
                  "code": "not_acceptable",
                  "resolution": "Retry with an Accept header this resource can satisfy — text/html or text/markdown for pages, application/json for API endpoints.",
                  "documentation": "https://www.neatmail.app/developers#errors"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/internal_error"
          }
        }
      }
    },
    "/api/v1": {
      "get": {
        "operationId": "getApiIndex",
        "summary": "Index of this API version",
        "description": "Every operation in this version, the versioning policy, the deprecation signals used, and where the error catalogue lives.",
        "responses": {
          "200": {
            "description": "API version index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/not_found"
          },
          "405": {
            "$ref": "#/components/responses/method_not_allowed"
          },
          "500": {
            "$ref": "#/components/responses/internal_error"
          }
        }
      }
    },
    "/api/v1/geo": {
      "get": {
        "operationId": "getGeo",
        "summary": "Country of the caller",
        "description": "Returns the caller's two-letter ISO 3166-1 country code, derived from the CDN edge. Used to pick a pricing currency. Never cached.",
        "responses": {
          "200": {
            "description": "Country code.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "country"
                  ],
                  "properties": {
                    "country": {
                      "type": "string",
                      "pattern": "^[A-Z]{2}$",
                      "examples": [
                        "US",
                        "IN"
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/not_found"
          },
          "405": {
            "$ref": "#/components/responses/method_not_allowed"
          },
          "500": {
            "$ref": "#/components/responses/internal_error"
          }
        }
      }
    },
    "/api/geo": {
      "get": {
        "operationId": "getDeprecatedApiGeo",
        "deprecated": true,
        "summary": "Deprecated alias for /api/v1/geo",
        "description": "Unversioned path kept for existing clients. It answers identically to `/api/v1/geo` and additionally sends `Deprecation: @1787443200`, `Sunset: Mon, 23 Aug 2027 00:00:00 GMT` and `Link: <https://www.neatmail.app/api/v1/geo>; rel=\"successor-version\"`. It may be removed after 2027-08-23. Use the versioned path.",
        "responses": {
          "200": {
            "description": "Same body as the successor operation.",
            "headers": {
              "Deprecation": {
                "description": "RFC 9745 sf-date: when the deprecation was announced.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "@1787443200"
                  ]
                }
              },
              "Sunset": {
                "description": "RFC 8594: earliest date this path may stop working.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "Mon, 23 Aug 2027 00:00:00 GMT"
                  ]
                }
              },
              "Link": {
                "description": "Carries rel=\"successor-version\" and rel=\"deprecation\".",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/not_found"
          },
          "405": {
            "$ref": "#/components/responses/method_not_allowed"
          },
          "500": {
            "$ref": "#/components/responses/internal_error"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getAppHealth",
        "summary": "NeatMail application health",
        "description": "Liveness plus database, cache and queue status for the NeatMail application. Served by the application origin, not the marketing site — so its error responses follow that application's conventions, not this origin's RFC 9457 model.",
        "servers": [
          {
            "url": "https://dashboard.neatmail.app",
            "description": "NeatMail application"
          }
        ],
        "responses": {
          "200": {
            "description": "Health report.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "llms.txt site index: every product, tool, guide and comparison page with a summary.",
        "responses": {
          "200": {
            "description": "llms.txt site index: every product, tool, guide and comparison page with a summary.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "operationId": "getWellKnownApiCatalog",
        "summary": "RFC 9727 API Catalog: links to the OpenAPI description, developer docs and status endpoint.",
        "responses": {
          "200": {
            "description": "RFC 9727 API Catalog: links to the OpenAPI description, developer docs and status endpoint.",
            "content": {
              "application/linkset+json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to the issuer that publishes this document (https://clerk.neatmail.app).",
            "headers": {
              "Location": {
                "description": "Absolute metadata URL.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "operationId": "getWellKnownOauthAuthorizationServer",
        "summary": "RFC 8414 authorization server metadata (redirects to the issuer that publishes it).",
        "responses": {
          "200": {
            "description": "RFC 8414 authorization server metadata (redirects to the issuer that publishes it).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to the issuer that publishes this document (https://clerk.neatmail.app).",
            "headers": {
              "Location": {
                "description": "Absolute metadata URL.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/openid-configuration": {
      "get": {
        "operationId": "getWellKnownOpenidConfiguration",
        "summary": "OpenID Connect discovery document (redirects to the issuer that publishes it).",
        "responses": {
          "200": {
            "description": "OpenID Connect discovery document (redirects to the issuer that publishes it).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to the issuer that publishes this document (https://clerk.neatmail.app).",
            "headers": {
              "Location": {
                "description": "Absolute metadata URL.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getSitemapXml",
        "summary": "Every indexable URL with its last-modified date.",
        "responses": {
          "200": {
            "description": "Every indexable URL with its last-modified date.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/robots.txt": {
      "get": {
        "operationId": "getRobotsTxt",
        "summary": "Crawler rules, including explicit allowances for AI crawlers.",
        "responses": {
          "200": {
            "description": "Crawler rules, including explicit allowances for AI crawlers.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiDocument",
        "summary": "This document.",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 description of the NeatMail site.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "title": "Problem",
        "description": "RFC 9457 problem details. `code` is the stable, machine-readable discriminator; branch on it rather than on `title` or on the status alone.",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "resolution"
        ],
        "additionalProperties": true,
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "Dereferenceable URI documenting this error class.",
            "examples": [
              "https://www.neatmail.app/developers#error-not-found",
              "https://www.neatmail.app/developers#error-not-acceptable",
              "https://www.neatmail.app/developers#error-method-not-allowed",
              "https://www.neatmail.app/developers#error-unsupported-api-version",
              "https://www.neatmail.app/developers#error-internal-error"
            ]
          },
          "title": {
            "type": "string",
            "description": "Short, stable summary of the error class."
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "HTTP status code, repeated for clients that only see the body."
          },
          "detail": {
            "type": "string",
            "description": "Explanation specific to this occurrence."
          },
          "instance": {
            "type": "string",
            "description": "Path that produced the error."
          },
          "code": {
            "type": "string",
            "enum": [
              "not_found",
              "not_acceptable",
              "method_not_allowed",
              "unsupported_api_version",
              "internal_error"
            ],
            "description": "Stable machine-readable error code."
          },
          "resolution": {
            "type": "string",
            "description": "What the caller should do next."
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "description": "Where the full error catalogue lives."
          }
        }
      }
    },
    "responses": {
      "not_found": {
        "description": "Resource not found",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://www.neatmail.app/developers#error-not-found",
              "title": "Resource not found",
              "status": 404,
              "detail": "Resource not found",
              "instance": "/api/v1/example",
              "code": "not_found",
              "resolution": "Check the path against https://www.neatmail.app/sitemap.xml (pages) or https://www.neatmail.app/openapi.json (endpoints).",
              "documentation": "https://www.neatmail.app/developers#errors"
            }
          }
        }
      },
      "not_acceptable": {
        "description": "No acceptable representation",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://www.neatmail.app/developers#error-not-acceptable",
              "title": "No acceptable representation",
              "status": 406,
              "detail": "No acceptable representation",
              "instance": "/api/v1/example",
              "code": "not_acceptable",
              "resolution": "Retry with an Accept header this resource can satisfy — text/html or text/markdown for pages, application/json for API endpoints.",
              "documentation": "https://www.neatmail.app/developers#errors"
            }
          }
        }
      },
      "method_not_allowed": {
        "description": "Method not allowed",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://www.neatmail.app/developers#error-method-not-allowed",
              "title": "Method not allowed",
              "status": 405,
              "detail": "Method not allowed",
              "instance": "/api/v1/example",
              "code": "method_not_allowed",
              "resolution": "Retry with a method listed in the Allow response header.",
              "documentation": "https://www.neatmail.app/developers#errors"
            }
          }
        }
      },
      "unsupported_api_version": {
        "description": "Unsupported API version",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://www.neatmail.app/developers#error-unsupported-api-version",
              "title": "Unsupported API version",
              "status": 404,
              "detail": "Unsupported API version",
              "instance": "/api/v1/example",
              "code": "unsupported_api_version",
              "resolution": "Only /api/v1 exists. See the versioning policy at https://www.neatmail.app/developers#versioning.",
              "documentation": "https://www.neatmail.app/developers#errors"
            }
          }
        }
      },
      "internal_error": {
        "description": "Internal server error",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://www.neatmail.app/developers#error-internal-error",
              "title": "Internal server error",
              "status": 500,
              "detail": "Internal server error",
              "instance": "/api/v1/example",
              "code": "internal_error",
              "resolution": "The request was not processed. Retry with backoff; if it persists, report it to help@send.neatmail.app.",
              "documentation": "https://www.neatmail.app/developers#errors"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "neatmailOAuth": {
        "type": "oauth2",
        "description": "Authorization server that signs users into the NeatMail application. Issuer: https://clerk.neatmail.app. RFC 8414 metadata: https://clerk.neatmail.app/.well-known/oauth-authorization-server. Authorization code with PKCE (S256). Client registration is not open to third parties yet — write to help@send.neatmail.app if you need one.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://clerk.neatmail.app/oauth/authorize",
            "tokenUrl": "https://clerk.neatmail.app/oauth/token",
            "refreshUrl": "https://clerk.neatmail.app/oauth/token",
            "scopes": {
              "openid": "Issue an ID token identifying the signed-in NeatMail user.",
              "profile": "Read the display name and avatar shown in the NeatMail app.",
              "email": "Read the verified email address the NeatMail account is keyed on.",
              "offline_access": "Issue a refresh token so background workers can keep processing a mailbox between sessions.",
              "public_metadata": "Read account metadata that the NeatMail app exposes to its own front end.",
              "private_metadata": "Read server-only account metadata such as plan and entitlement flags."
            }
          }
        }
      },
      "googleGmailOAuth": {
        "type": "oauth2",
        "description": "Delegated Gmail access a user grants to NeatMail at Google, not a credential for calling this API. These are the only scopes NeatMail requests; revoke them at https://myaccount.google.com/permissions.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
            "tokenUrl": "https://oauth2.googleapis.com/token",
            "refreshUrl": "https://oauth2.googleapis.com/token",
            "scopes": {
              "openid": "Issue an ID token identifying the connected Google account.",
              "https://www.googleapis.com/auth/userinfo.email": "Read the verified email address the NeatMail account is keyed on.",
              "https://www.googleapis.com/auth/userinfo.profile": "Read the display name and avatar shown in the NeatMail app.",
              "https://www.googleapis.com/auth/gmail.readonly": "Read message and thread data to classify incoming mail, detect promises, and assemble the context a draft reply is written from.",
              "https://www.googleapis.com/auth/gmail.labels": "Create and maintain the NeatMail label set (including the single 'Follow up' label).",
              "https://www.googleapis.com/auth/gmail.modify": "Apply and remove those labels on messages, auto-archive mail that matches your archive rules, and move mail to Trash when you ask.",
              "https://www.googleapis.com/auth/gmail.compose": "Create draft replies and follow-ups in your mailbox, send a draft when you approve it (in the app or from Telegram), and send the unsubscribe requests you trigger. Nothing is sent without an action from you.",
              "https://www.googleapis.com/auth/calendar.readonly": "Read free/busy blocks and upcoming events, so a draft can check whether a time proposed in an email is actually free, offer times you are available, and resolve a deadline that names an event rather than a date. Read-only: NeatMail never creates or edits events."
            }
          }
        }
      },
      "microsoftGraphOAuth": {
        "type": "oauth2",
        "description": "Delegated Outlook / Microsoft Graph access a user grants to NeatMail at Microsoft. These are the only scopes NeatMail requests; revoke them at https://myaccount.microsoft.com/permissions.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
            "tokenUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
            "refreshUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
            "scopes": {
              "openid": "Issue an ID token identifying the connected Microsoft account.",
              "email": "Read the account's primary email address.",
              "profile": "Read the display name shown in the NeatMail app.",
              "offline_access": "Issue a refresh token so background workers can keep processing the mailbox.",
              "User.Read": "Read the signed-in user's basic Microsoft profile.",
              "Mail.ReadWrite": "Read mail for classification and drafting, apply NeatMail categories and folders, create draft replies, and send the drafts and unsubscribe requests you approve.",
              "MailboxSettings.ReadWrite": "Requested on the Microsoft consent screen, but NeatMail currently makes no mailbox-settings call — no code path reads or writes your time zone or automatic replies. It is a candidate for removal from the consent screen.",
              "Calendars.Read": "Read free/busy blocks and upcoming events, so a draft can check whether a time proposed in an email is actually free, offer times you are available, and resolve a deadline that names an event rather than a date. Read-only: NeatMail never creates or edits events."
            }
          }
        }
      }
    }
  }
}