MailerDot Developer Documentation

Authentication

None. Every endpoint below is public and read-only — one exception, POST /api/subscribe — and needs no key, token, account, or sign-up. There is no sandbox because there is nothing to break: the read endpoints cannot mutate anything, so you can develop against production directly.

Quickstart

# 1. Find a city
curl -s 'https://mailerdot.com/api/cities'

# 2. Read its latest edition as markdown
curl -s 'https://mailerdot.com/austin-texas.md'

# 3. Search every archive
curl -s 'https://mailerdot.com/api/search?q=farmers+market&limit=3'

City slugs

Every endpoint is keyed by a slug of the form `{city}-{state-name}`, lowercased and hyphenated — `austin-texas`, `san-francisco-california`, `new-york-new-york`. The state is the full name, not the postal abbreviation. Fetch https://mailerdot.com/api/cities for the authoritative list.

API endpoints

Full parameters and response schemas: https://mailerdot.com/openapi.json

Error responses

Every failure answers with application/problem+json (RFC 9457) — never an HTML page, on any path under /api/, including ones that do not exist. Branch on code; it is stable. resolution says what to do next, and issues[] lists per-field failures on a validation error.

Markdown for agents

Every page has a markdown twin. Append .md to the path, or send Accept: text/markdown. Responses carry an X-Markdown-Tokens header with a rough token estimate.

• https://mailerdot.com/{slug}.md — A city page: latest edition, archive index, census table.
• https://mailerdot.com/{slug}/{YYYY-MM-DD}.md — One dated edition, in full.
• https://mailerdot.com/cities.md — The whole city directory.
• https://mailerdot.com/states/{state}.md — Every tracked city in one state, by population.
• https://mailerdot.com/feed.md — The 30 most recent editions across all cities.
• https://mailerdot.com/developers.md — This page.

MCP server

https://mailerdot.com/mcp speaks the Model Context Protocol over streamable HTTP, unauthenticated. Point any MCP client at it:

{
  "mcpServers": {
    "mailerdot": {
      "url": "https://mailerdot.com/mcp"
    }
  }
}

Tools:

• list_cities — Every city with an active newsletter, grouped by state.
• get_city — City overview: subscribers, census demographics, recent editions.
• get_archive — Read a past edition as markdown.
• search_archives — Full-text search across every edition.
• get_weather — Today's weather for a city.

It also serves resources/list, resources/templates/list, resources/read, and prompts/list.

Machine-readable discovery

• OpenAPI 3.1 specification application/json — The full contract: every endpoint, schema, and error code. Generate a client from it.
• MCP server application/json — Model Context Protocol over streamable HTTP. Tools, resources, and prompts.
• API catalog (RFC 9727) application/linkset+json — Linkset pointing at everything on this list. The standard discovery entry point.
• Agent Skills index application/json — A SKILL.md an agent can load to learn the URL shapes without crawling for them.
• llms.txt text/plain — What MailerDot is, in one page, written for a language model.
• llms-full.txt text/plain — The long form: product, editorial policy, operator terms, and API notes.
• RSS feed application/rss+xml — The most recent editions across every city.
• Sitemap index application/xml — Every indexable URL: cities, states, and dated editions.

Limits and conventions

• No API key, no account, no rate limit on the read endpoints. Be reasonable and cache what you fetch — responses carry real `Cache-Control` headers, so honouring them costs you nothing.
• Every read endpoint sends `Access-Control-Allow-Origin: *`, so browser-side agents can call them directly.
• Markdown responses carry an `X-Markdown-Tokens` header with a rough token estimate, so you can decide whether to fetch a full edition or stop at the summary.
• Editions publish each morning in the city's own timezone. Asking for today's edition before it publishes returns a 404 with the `edition_not_found` code, not the previous day's content.
• Coverage is the United States only.

Support

• Questions and bug reports: https://mailerdot.com/contact — we reply within 3 business days
• Security reports: security.txt
• Terms · Privacy