Agents & routing
Send a message to one of your inbox agents and get its reply, or run a registered route directly. See Connect your agent for a guided walk-through.
Auth: API key · Base URL:
https://api.mailkite.dev
Endpoints
Each row expands to its request and response schema. The address bar follows along, so any endpoint can be linked to directly.
POST /v1/agent Send a message to one of your inbox agents and get its reply. Defaults to the account's default agent; pass `routeId` or `address` to target a specific agent, or `model` to override the model. This is separate from inbound routing — it does not match or override routes.
Send a message to one of your inbox agents and get its reply. Defaults to the account's default agent; pass `routeId` or `address` to target a specific agent, or `model` to override the model. This is separate from inbound routing — it does not match or override routes.
Request body
agent-request.json| Field | Type | Notes |
|---|---|---|
| text req | string | The message for the agent — it reads this as the incoming email body and decides what to do. |
| subject | string | Optional subject line the agent sees on the message. |
| from | string | Optional sender address the agent sees as the originator. Defaults to the account's API caller address. |
| html | string | Optional HTML body. `text` is still required — the agent reasons over the plain-text content. |
| routeId | string | Target a specific agent by its route id (rte_…). Omit to use the account's default agent (its most recently created agent route). |
| address | string | Target the agent whose route matches this address. Alternative to routeId. |
| model | string | Override the model the agent runs on for this call (e.g. claude-sonnet-4-6). |
The smallest body that makes this call — every other field is optional.
request.json
{
"text": "What's my current balance?"
} agent-request.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://api.mailkite.dev/v1/schemas/agent-request.json",
"title": "Send-to-agent request body",
"type": "object",
"required": [
"text"
],
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"description": "The message for the agent — it reads this as the incoming email body and decides what to do."
},
"subject": {
"type": "string",
"description": "Optional subject line the agent sees on the message."
},
"from": {
"type": "string",
"description": "Optional sender address the agent sees as the originator. Defaults to the account's API caller address."
},
"html": {
"type": "string",
"description": "Optional HTML body. `text` is still required — the agent reasons over the plain-text content."
},
"routeId": {
"type": "string",
"description": "Target a specific agent by its route id (rte_…). Omit to use the account's default agent (its most recently created agent route)."
},
"address": {
"type": "string",
"description": "Target the agent whose route matches this address. Alternative to routeId."
},
"model": {
"type": "string",
"description": "Override the model the agent runs on for this call (e.g. claude-sonnet-4-6)."
}
}
}Response body
agent-response.json| Field | Type | Notes |
|---|---|---|
| ok req | boolean | Whether the agent ran to completion. |
| text | string | The agent's reply — its final message after running. |
| messageId | string | Id of the stored message the agent processed (msg_…). |
| error | string | Error detail when `ok` is false. |
An actual response, recorded from the conformance suite.
response.json
{
"ok": true,
"text": "Your balance is $0.00.",
"messageId": "msg_agent"
} agent-response.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://api.mailkite.dev/v1/schemas/agent-response.json",
"title": "Send-to-agent response body",
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"description": "Whether the agent ran to completion."
},
"text": {
"type": "string",
"description": "The agent's reply — its final message after running."
},
"messageId": {
"type": "string",
"description": "Id of the stored message the agent processed (msg_…)."
},
"error": {
"type": "string",
"description": "Error detail when `ok` is false."
}
}
}POST /v1/route Route a message to one of your registered routes (by `routeId` or `address`), running that route's action — agent, webhook, or forward. The route must already exist on your account; arbitrary destinations are not allowed.
Route a message to one of your registered routes (by `routeId` or `address`), running that route's action — agent, webhook, or forward. The route must already exist on your account; arbitrary destinations are not allowed.
Request body
route-message-request.json| Field | Type | Notes |
|---|---|---|
| routeId | string | Target route by id (rte_…). One of routeId or address is required. The route must already be registered on this account. |
| address | string | Target route by the address it matches. One of routeId or address is required. |
| from req | string | Sender address recorded on the message. |
| subject | string | Optional subject line. |
| text | string | Plain-text body. |
| html | string | HTML body. |
The smallest body that makes this call — every other field is optional.
request.json
{
"address": "support@app.mailkite.dev",
"from": "ops@example.com",
"text": "hey there"
} route-message-request.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://api.mailkite.dev/v1/schemas/route-message-request.json",
"title": "Route-message request body",
"type": "object",
"required": [
"from"
],
"additionalProperties": false,
"anyOf": [
{
"required": [
"routeId"
]
},
{
"required": [
"address"
]
}
],
"properties": {
"routeId": {
"type": "string",
"description": "Target route by id (rte_…). One of routeId or address is required. The route must already be registered on this account."
},
"address": {
"type": "string",
"description": "Target route by the address it matches. One of routeId or address is required."
},
"from": {
"type": "string",
"description": "Sender address recorded on the message."
},
"subject": {
"type": "string",
"description": "Optional subject line."
},
"text": {
"type": "string",
"description": "Plain-text body."
},
"html": {
"type": "string",
"description": "HTML body."
}
}
}Response body
route-response.json| Field | Type | Notes |
|---|---|---|
| id req | string | Stored message id (msg_…). |
| routed req | boolean | Whether the message was handed to the route's action. |
| action req | string | The action the matched route performed: webhook, forward, agent, store, or drop. |
An actual response, recorded from the conformance suite.
response.json
{
"id": "msg_r1",
"routed": true,
"action": "webhook"
} route-response.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://api.mailkite.dev/v1/schemas/route-response.json",
"title": "Route-message response body",
"type": "object",
"required": [
"id",
"routed",
"action"
],
"properties": {
"id": {
"type": "string",
"description": "Stored message id (msg_…)."
},
"routed": {
"type": "boolean",
"description": "Whether the message was handed to the route's action."
},
"action": {
"type": "string",
"description": "The action the matched route performed: webhook, forward, agent, store, or drop."
}
}
}