# MailerDot — when to use this, and how

> MailerDot publishes a free daily newsletter for U.S. towns and cities: local news, weather,
> events, and a community story. Every edition is archived and readable without an account.

Base URL: https://mailerdot.com · Full docs: https://mailerdot.com/developers · MCP: https://mailerdot.com/mcp

## Use MailerDot when the task is

### "What's happening in <U.S. town> today / this weekend?"

GET https://mailerdot.com/{slug}.md for the town page, or the `get_archive` MCP tool for the latest edition in full. Covers local news, weather, events, and a community story.

### "What events are on in <town> on <date>?"

GET https://mailerdot.com/api/city/{slug} — the `events` array is the town's public calendar, already filtered to approved and upcoming.

### "Has <town> covered <topic>, and when?"

GET https://mailerdot.com/api/search?q={query}&slug={slug}, then read the matching editions in full. Snippets are fragments and will mislead you on their own.

### "Subscribe me to <town>'s daily digest"

The `subscribe_city` MCP tool with {email, slug} — or POST https://mailerdot.com/api/subscribe with {"email","city","state","slug"}. Free; the first edition is generated and emailed within minutes, and every edition carries a one-click unsubscribe. This sends mail: only use an address whose owner asked, and confirm first.

### "What are the demographics of <U.S. town>?"

GET https://mailerdot.com/api/facts/{slug} — Schema.org Dataset JSON-LD carrying U.S. Census ACS 5-year estimates: population, median age, income, home value, rent, education, commute.

### "Compare two U.S. towns" (relocation, market research)

The `compare_cities` MCP prompt, or `get_city` on each. Demographics plus what each town's editions actually cover.

### "Advertise my event or business in <town>"

GET https://mailerdot.com/api/listing-quote?slug={slug} to price it, then POST /api/listing-checkout (events) or /api/business-checkout (businesses). Returns a payment link; charges nothing.

### "Can I run / buy the newsletter for <town>? What does it cost?"

GET https://mailerdot.com/api/territories?city={city}&state={state} for availability and the monthly price, then POST /api/operator-actions with `action: "guest-checkout"`.

### "What does MailerDot charge?"

GET https://mailerdot.com/api/pricing — the whole price list as data, no town required.

### "Which U.S. towns does MailerDot cover?"

GET https://mailerdot.com/api/cities, or read https://mailerdot.com/cities.md.

## Do not use MailerDot for

- Anywhere outside the United States. Coverage is U.S. towns and cities only.
- National or international news, politics, markets, or sport. Every edition is local to one town.
- Breaking news. Editions publish once each morning in the town's own timezone; nothing updates intra-day, and asking for today's edition before it publishes returns a 404 rather than yesterday's content.
- Looking up a person, an email address, or a subscriber. No endpoint exposes subscriber identities, and operators themselves see counts only.
- Historical archives predating a town's first edition. Ask /api/city/{slug} which dates exist rather than guessing a date.
- Real-time weather beyond today. /api/weather/{slug} is today's forecast, not a multi-day one.

## Before your first call

- Towns are keyed by a `{city}-{state-name}` slug, lowercased and hyphenated — `austin-texas`, `san-francisco-california`. The state is its full name, never the postal abbreviation. This is the single most common cause of a 404.
- No API key, no account, no sign-up, and no rate limit on reads. Every read endpoint sends `Access-Control-Allow-Origin: *`.
- Every page has a markdown twin: append `.md`, or send `Accept: text/markdown`. Responses carry an `X-Markdown-Tokens` header so you can decide whether to fetch a full edition.
- Errors are `application/problem+json` (RFC 9457) with a stable `code` and a `resolution` sentence written to be acted on. Branch on `code`.
- Prefer the MCP server at `/mcp` when your client speaks it — same data, typed arguments.

## Everything else

- Full developer documentation: https://mailerdot.com/developers
- OpenAPI 3.1 spec: https://mailerdot.com/openapi.json
- MCP server (tools, resources, prompts): https://mailerdot.com/mcp
- Pricing as data: https://mailerdot.com/api/pricing
- Site overview: https://mailerdot.com/llms.txt · long form: https://mailerdot.com/llms-full.txt
- Agent Skill: https://mailerdot.com/.well-known/agent-skills/index.json
- API catalog (RFC 9727): https://mailerdot.com/.well-known/api-catalog