Documentation

Kontacts gives a project a mailbox: an inbound address, a way to send, and a way to react to what happens to both. This site documents the programmatic surface — the parts you call from code or point an agent at, rather than click in the dashboard.

There is no published SDK. Every example on this site is a plain curl command or a fetch call — copy it, swap in your own key, and it runs.

The five surfaces

Authentication

The two key formats, what each can do, and how a request is authorized.

Send an email

/api/v1/send — the one way to send outbound mail.

List emails

/api/v1/emails — read a project's mailbox.

Projects

List the projects a key can see, or create one with an org-wide key.

Webhooks

Signed, outbound HTTP events for mail, forms, and bookings.

MCP for agents

/api/v1/mcp — the same account, exposed as 6 tools.

How the pieces fit together

Sending and reading are plain REST: POST to send, GET to list. There is no from field on send — the project you send from decides the address.
Projects are the unit everything else hangs off. A project key can only act as its own project; an org-wide key can act as any project in the organisation, including creating new ones.
Webhooks are the only push channel. Kontacts calls you — there is no polling endpoint that tells you "what changed since X."
MCP wraps the same account (mail, domains, bookings, send) as tools for an agent, over the same Bearer key as the REST API.

What Kontacts does not have

No IMAP. No published SDK or npm client — curl, fetch, or MCP. No REST endpoint for a single message (that's the MCP get_email tool). No self-serve data export. No uptime guarantee or SLA — see kontacts.dev/terms. These are current limits, not a roadmap promise either way.

Authentication, in short

Every request on this site carries one header:

Authorization: Bearer <key>

A key is either a project key (gm_live_…, scoped to exactly one project) or an org/scoped key (jwt_…, scoped to an organisation, a list of workspaces, or a list of projects). Which one you need is called out on each page — most read/send operations accept either, but creating a project requires an org-wide key. See Authentication for the full picture, including what each format cannot do.

Sending limits

Free plan sending is capped at 10 messages per organisation, per UTC day — one pool shared by every project in the organisation, not 10 per project. Indie Hacker raises that to 200/day and 1,000/month. Receiving has no per-day cap on either plan. Every send-capable surface (REST, MCP send_email/reply_email) spends the same pool, so a script and a teammate sending from the dashboard draw from the same number.

Receiving requires a domain you control, with DNS records pointed at Kontacts — there is no ready-made @kontacts.dev address to send through instead.