Postmark is Needs Work to agents.

Item: Postmark API
Rating: 60
Author: Discry

Discry independently scored how well an AI agent can discover and understand the Postmark API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.

Discry your API — free View the docs ↗

SCORED UNDER RUBRIC 1.2 · A full re-launch under Discry Score 2.5 — a new behavioral instrument, not comparable to these scores — is in progress.

Discovery

45% of score · 36/100

OpenAPI specA machine-readable OpenAPI/Swagger spec agents can parse.Fail

llms.txtAn llms.txt index that points agents to the docs that matter.Pass

llms.txt qualityThe llms.txt is focused, current, and well under the size budget.Partial

llms-full.txtA full-text bundle agents can load in one request.Fail

AGENTS.mdAn AGENTS.md that tells coding agents how to build on the API.Fail

.well-known/mcp.jsonA discoverable MCP manifest at a well-known path.Fail

MCP registryThe API is listed in a public MCP registry.Fail

robots.txt AI directivesrobots.txt allows (or explicitly guides) AI crawlers.Partial

SitemapA sitemap so agents can enumerate the docs surface.Pass

Comprehension

55% of score · 79/100

Task-oriented descriptionsEndpoints described by what they accomplish, not just their shape.Pass

Realistic examplesRunnable, real-world request/response examples.Pass

Multi-step workflowsDocs that chain calls into complete jobs an agent can follow.Partial

Error-recovery guidanceDocumented failure modes and how to recover from them.Partial

Answer-first formatThe answer leads; preamble does not bury it.Pass

Capability boundariesClear limits — what the API can and cannot do.Pass

Naming consistencyConsistent, predictable naming across endpoints.Pass

Heading hierarchyClean heading structure agents can navigate.Pass

Markdown docsDocs available as clean markdown, not JS-rendered HTML only.Partial

Token efficiencyDocs are concise enough to fit an agent context window.Partial

What we found

Postmark has a well-structured llms.txt (62KB) with Quick Start, API Reference, and Core Concepts sections — but it's slightly over the ideal 50KB threshold
No OpenAPI spec is publicly accessible — this is the single highest-impact discovery gap given its weight of 5
API documentation is clear and example-rich with curl examples using realistic values, but only available in curl — no multi-language SDK examples on endpoint pages
The llms.txt explicitly documents Key Limitations (message size, recipients, batch limits) which is excellent for agent capability boundary understanding
No MCP registry presence, no .well-known/mcp.json, and no AGENTS.md — Postmark is nearly invisible to agent discovery mechanisms

What to change

Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.

01Publish an OpenAPI spec at postmarkapp.com/openapi.json or link to one in the developer docs — this would add 5 points to discovery
02Add .well-known/mcp.json with tool declarations for the core email sending capabilities
03Register on MCP directories (Glama, PulseMCP) or publish an official Postmark MCP server
04Add multi-language code examples (Node.js, Python, Ruby) alongside the existing curl examples on API reference pages
05Add explicit error recovery guidance — current error codes lack 'what to do next' steps

Execution coverage · INFORMATIONAL, UNSCORED

Whether an agent can actually complete a call and recover from errors is the deeper Audit layer — documented here, but not part of the Discry Score.

api_key✓ Error format documented✓ Rate limits documented✓ Pagination documented✕ Idempotency documented

Good execution documentation. Server token auth via X-Postmark-Server-Token header. JSON error responses with numeric error codes. Rate limits and pagination documented. Batch endpoint accepts 500 messages/call with 50MB payload limit.

See your own Discry Score.

Drop your API docs URL. See what an agent sees — in 60 seconds, free.

Discry your API — free