REST API
Plain HTTP routes for your own code (a backend, a script, a CRM sync) to read or change Kata; for an AI, connect it to the MCP server instead, where every tool is one call.
Base URLhttps://api.katasend.com/api
Try it: get one campaign
curl -s https://api.katasend.com/api/campaigns/1 \
-H "Authorization: Bearer $KATA_KEY"Authentication
The MCP server and the REST API take your agent key in this header, on every request:
Request header
Authorization: Bearer <your key>- Body
- JSON, with
Content-Type: application/json. CSV imports send the raw CSV text instead. - Errors
- A missing or wrong key gets
401 {"error": "unauthorized"}. A route for signed-in people only gets403.
Routes
| Method | Path | What it does |
|---|---|---|
| Read data | ||
| GET | /api/overview | Everything the dashboard shows: KPIs, campaigns, angles, domains, mailboxes, recent emails and events, health, leads to call. |
| GET | /api/campaigns/{id} | One campaign: stats, last 14 days, angles, steps, files, lead lists, brief.md, interested leads. |
| GET | /api/campaigns/{id}/mailboxes | Which mailboxes the campaign sends from. |
| GET | /api/health | Health scores of every domain and mailbox. |
| GET | /api/days?period={7d|30d|90d|all} | The bars of a chart, one per day: sent, replies, interested, clicks, conversions, bounces. Add campaign_id for one campaign or list_id for one lead list. /api/overview, /api/campaigns/{id} and /api/crm/list take the same period. |
| GET | /api/export?kind={events|messages} | A CSV file: the activity log (events) or the emails (messages). Filters: campaign_id, type (event type or message status), mailbox, period. Same as export_csv. |
| GET | /api/summary | The home summary. Add ?fresh=1 to rebuild it. |
| GET | /api/canvas | Everything the Canvas draws. |
| GET | /api/crm | Every lead list with its numbers. |
| GET | /api/crm/list?id={id} | One list with its numbers. 0 = everyone, -1 = contacts in no list. |
| GET | /api/contact-counts | Total contacts, unreachable contacts, contacts in no list. |
| GET | /api/context | Context files. Filters: ?campaign_id=, ?scope=company|campaign. |
| GET | /api/context/file?id={id} | One context file with its content. |
| GET | /api/settings | Configured integrations (never the keys), the MCP URL and the API base. |
| GET | /api/mailboxes/providers | Mailbox providers you can create or connect. |
| GET | /api/warmup | Warmup state of the mailboxes in Instantly. |
| Change things | ||
| POST | /api/campaigns/{id}/mailboxes | Choose them. Body: {all}, {emails}, or {add, remove}. |
| POST | /api/import?campaign={id} | Import a CSV. The body is the raw CSV text. campaign is optional: with it, new contacts enter the sequence. |
| POST | /api/variants | Add an angle. Body: {campaign_id, step, angle, subject, body}. |
| POST | /api/conversion | Report a conversion. Body: {token or email, value, event, note, data}. Same effect as the postback. |
| POST | /api/handled | Mark an interested lead as handled. Body: {contact_id, undo}. |
| Run jobs | ||
| POST | /api/campaigns/{id}/check-brief | Check the campaign's brief.md (same as check_campaign_brief). |
| POST | /api/sendingAffects all campaigns | Global switch. Body: {on: false} pauses every active campaign; {on: true} resumes the paused ones. |
| POST | /api/evolve | Run the evolve job now: retire losing angles, write new ones. |
| POST | /api/tickSends email | Run the scheduler now. This really sends. |
| Agent | ||
| GET | /api/agent/tools | The MCP tools: name, description, parameter names, required ones. |
| GET | /api/agent/conversations | The built-in agent's conversations. |
| GET | /api/agent/chat?c={id} | One conversation's transcript. |
Some routes of the app are for signed-in people only (settings, keys, chat, and most changes made from the pages). Called with a key, they answer
403. Use the matching MCP tool instead.Send data
Import a CSV
curl -s -X POST "https://api.katasend.com/api/import?campaign=1" \
-H "Authorization: Bearer $KATA_KEY" \
--data-binary @leads.csvCalling MCP tools over HTTP
Any tool can be called with one POST, no MCP client needed:
Add leads with one POST
curl -s https://api.katasend.com/mcp \
-H "Authorization: Bearer $KATA_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add_leads","arguments":{"list_id":3,"leads":[{"email":"jane@acme.com","first_name":"Jane"}]}}}'The answer's result.structuredContent holds the tool's result as JSON. Errors come back with result.isError: true.
All Kata URLs
| What | URL |
|---|---|
| REST API | https://api.katasend.com/api |
| MCP server | https://api.katasend.com/mcp |
| App | https://katasend.com/app |
| Lead list webhook | https://api.katasend.com/hooks/lists/<token> |
| Conversion postback | https://api.katasend.com/hooks/postback/<key> |
Webhook URLs carry their own secret, so they need no key. See Webhooks.