# InboxStack developer portal

InboxStack publishes a read-only content API so agents and scripts can use the deliverability writing, the mailbox-provider news timeline, and the free tools without scraping HTML.

**Scope.** Public content only. This is not the InboxStack product API — it exposes nothing about accounts, monitored domains, or customer data, and has no write operations.

- **Base URL:** `https://inboxstack.com/api/v1`
- **OpenAPI 3.1:** https://inboxstack.com/openapi.json (also https://inboxstack.com/openapi.yaml)
- **MCP server:** https://inboxstack.com/mcp (Streamable HTTP)
- **Authentication:** none. No key, no signup, no OAuth. Do not send credentials.
- **Rate limit:** not enforced. Keep sustained traffic under roughly 60 requests per minute.
- **CORS:** `Access-Control-Allow-Origin: *` on every endpoint.

## Quickstart

```sh
curl -s https://inboxstack.com/api/v1 | jq
curl -s "https://inboxstack.com/api/v1/articles?limit=5" | jq '.data[].title'
curl -s "https://inboxstack.com/api/v1/email-news?q=gmail+bulk+sender" | jq '.data[0]'
curl -s https://inboxstack.com/api/v1/articles/bimi-setup-guide | jq -r .content_markdown
```

## Endpoints

| Operation | Method | Path | Purpose |
| --- | --- | --- | --- |
| `getApiIndex` | GET | `/api/v1` | Discovery document listing every endpoint. |
| `getOverview` | GET | `/api/v1/overview` | What InboxStack is, capabilities, when to use it. |
| `listArticles` | GET | `/api/v1/articles` | Deliverability articles. `?tag=`, `?limit=`, `?offset=`. |
| `getArticle` | GET | `/api/v1/articles/{slug}` | One article including its full Markdown body. |
| `searchContent` | GET | `/api/v1/search` | Relevance-ranked search. `?q=` required. |
| `listEmailNews` | GET | `/api/v1/email-news` | Dated rule changes. `?q=`, `?category=`, `?limit=`. |
| `listFreeTools` | GET | `/api/v1/free-tools` | The free, no-account diagnostic tools. |

## Errors

Every failure is JSON with the same envelope — never an HTML page.

```json
{
  "error": {
    "code": "not_found",
    "status": 404,
    "message": "No article with slug \"nope\".",
    "hint": "List valid slugs at /api/v1/articles.",
    "documentation_url": "https://inboxstack.com/developers",
    "openapi_url": "https://inboxstack.com/openapi.json"
  }
}
```

Codes: `not_found` (404), `invalid_request` (400), `method_not_allowed` (405), `unsupported_media_type` (415), `internal_error` (500). Branch on `code`; recover with `hint`.

## MCP server

The same content is exposed over the Model Context Protocol at `https://inboxstack.com/mcp` (Streamable HTTP). Stateless, read-only, no authentication.

| Tool | Returns |
| --- | --- |
| `inboxstack_search_writing` | Relevance-ranked search over the articles. |
| `inboxstack_get_article` | One article in full Markdown. |
| `inboxstack_list_articles` | Article metadata, optionally by tag. |
| `inboxstack_search_email_news` | Search the dated rule-change timeline. |
| `inboxstack_list_free_tools` | The free diagnostic tools. |
| `inboxstack_get_overview` | What InboxStack is and when to use it. |

## Markdown representations

Every page is available as Markdown at the same canonical URL:

```sh
curl -s -H "Accept: text/markdown" https://inboxstack.com/blog
curl -s https://inboxstack.com/blog.md
```

Responses carry `Vary: Accept, Accept-Encoding`, so shared caches keep the HTML and Markdown variants separate.

## Other machine surfaces

- Site guide for agents: https://inboxstack.com/llms.txt
- Full text, every page and post: https://inboxstack.com/llms-full.txt
- Agent instructions: https://inboxstack.com/.well-known/agent-instructions
- API catalog (RFC 9727): https://inboxstack.com/.well-known/api-catalog
- AI catalog: https://inboxstack.com/.well-known/ai-catalog.json
- MCP server card: https://inboxstack.com/.well-known/mcp/server-card.json
- MCP registry manifest: https://inboxstack.com/server.json
- Sitemap: https://inboxstack.com/sitemap.xml · RSS: https://inboxstack.com/feed.xml

## Versioning and deprecation policy

The path carries the major version. Additive changes ship inside `v1`; anything that removes or renames a field ships as `v2` at a new path while `v1` keeps serving.

Every response advertises its version in `X-Api-Version` and links this policy as `Link: <.../developers#versioning-and-deprecation>; rel="deprecation"`. While a version is current, `X-Api-Deprecated: false` is returned.

When a version is deprecated:

- `X-Api-Deprecated` flips to `true` and a `Deprecation` header (RFC 9745) carries the date it took effect.
- A `Sunset` header (RFC 8594) carries the shutdown date — never less than **180 days** later.
- The deprecated version keeps serving unchanged until its sunset date. Nothing is removed silently.
- After the sunset date the path returns `410 Gone` with the usual error envelope, whose `hint` names the successor.

**Current status:** `v1` is current and not deprecated. No sunset date is set.

Deliverability guidance published by InboxStack is general advice, not a guarantee of inbox placement.

---

Canonical HTML: https://inboxstack.com/developers
Site guide for agents: https://inboxstack.com/llms.txt · Agent instructions: https://inboxstack.com/.well-known/agent-instructions