Test channel connectivity
POST /api/channels/{channelId}/test
Test an email channel against what its setup needs to go live, and move its status forward from the answer. A subdomain channel passes when the domain of from_address is verified for sending, its DKIM records are verified and its MX record resolves to the inbound endpoint, and a pass sets it active. A mail_routing_rule channel passes when the DKIM records of its domain are verified; a pass moves a channel still waiting for its DKIM records (pending_dns) on to pending_setup and leaves any other status as it is, since the channel turns active when the first message its mail-flow rule redirects arrives. A failure sets an active channel to error; a channel still waiting for its records keeps its status, and missingRecords names the records it waits on. An MX lookup that gets no answer decides nothing: unconfirmedRecords names it and the status stays as it was. The test never sets a status earlier than the channel’s own, and a deleted channel keeps its status. A forwarding channel sends its replies from oHallo’s own address and an inbox_api channel sends through its mailbox provider, so for those two the test answers 422 with error: test_not_applicable and the status stays as it was. On an account whose billing is suspended or closed, the test answers 409 with error: billing_restricted and the status stays as it was.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The unique identifier of the channel to test.
Responses
Section titled “ Responses ”The test completed. Check the ‘ok’ field for the result, and ‘status’ for where the channel stands.
The answer of a channel test: whether the channel passed, its status after the test, the records its setup still waits on, and the records whose lookup gave no answer.
object
Whether the channel passed the test.
The channel’s status after the test, one of the channel statuses.
Example
pending_dnsOn a failed test of an email channel: the records its setup still waits on, by the purpose of the DNS record. verification: the domain of from_address is verified for sending. dkim: the DKIM records are verified. mx: the MX record resolves to the inbound endpoint.
Example
[ "mx"]The records whose check gave no answer: an MX lookup that timed out or was refused. Such a test decides nothing and writes no status; run it again in a moment.
Example
[ "mx"]Unless the test passed: why, and what to do next.
Example
Records still to verify on help.example.com: MX. Publish them as listed under DNS records, then run the test again.The caller may not change this channel. People need the owner or admin role. An API key needs the channels:write scope; a channel in a workspace outside the key’s brand or workspace restriction answers 404.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]No channel exists with the given ID in the authenticated tenant.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]The account’s billing is suspended or closed (error: billing_restricted). A test can activate a channel, which is new capacity, so it is refused, and the status stays as it was.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]The test does not apply to this channel: a forwarding or inbox_api email channel answers error: test_not_applicable, and its status stays as it was.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]