REST API: channels

Use the Channels API to configure agent email and Slack channels from a backend provisioning flow. Before you patch the channel settings of an agent, read the current settings. Treat email addresses, blocked senders, and the primary address as separate resources. After you update the primary address, read back the settings to confirm the change. This step matters most when the agent has more than one address.

PATCH /agents/{id}/channels/email needs at least one field that the endpoint can update. An empty object, a body with no recognized update, or a body that fails schema validation returns 400 VALIDATION_ERROR. Read the current settings first. Then send only the fields that must change.

Email domain setup uses a staged verification process. Create or list domains. Request receiving setup. Publish the required DNS records. Then verify them. A requested verification is not the same as completed delivery capability. You can verify or disable receiving as separate operations. Treat domain deletion as a deliberate action. It has a known effect on mail flow.

Slack channel discovery lists the available channels. It does not by itself activate an agent in a channel. Use the documented Slack settings payload to update the intended agent. Keep external provider tokens and AgentStack API keys in the backend. When verification fails, log the returned envelope. Do not retry DNS changes without a clear reason.

Refusals on the Slack config updateCopy Anchor Link

PATCH /agents/{id}/channels/slack answers a different status for each kind of refusal. Match on the error code, not on the status.

• 400 VALIDATION_ERROR — the body sets no field, or the Slack Connect settings are incomplete. Connect mode needs at least one shared Connect channel, an internal triage channel, and a Slack connection. A Connect channel that is not shared, and a triage channel that is shared, are refused the same way.
• 404 AGENT_NOT_FOUND — the agent is not in your organization.
• 410 AGENT_UNAVAILABLE — the agent waits for deletion. Call POST /agents/{id}/cancel-delete first, then retry.
• 412 NOT_CONNECTED — your organization has no Slack connection. Connect Slack first, then retry.
• 502 SLACK_ERROR — the call to Slack failed. A Slack outage, a timeout, and a Slack API error all arrive as this code. Retry with backoff.

GET /channels/slack/channels also answers 412 NOT_CONNECTED in two cases. The first is a missing connection. The second is a connection that Slack no longer accepts: an expired, revoked, or deauthorized token, or a connection that lost a required scope. The message tells the two apart, and only the second one asks you to reconnect. A reconnect is a human action in the dashboard, so do not retry this refusal.

Refusals on receiving verificationCopy Anchor Link

POST /channels/email/domains/{domainId}/receiving/verify refuses in five ways.

• 400 APEX_NOT_ALLOWED — receiving needs a subdomain such as support.example.com. An apex hostname cannot carry the MX record.
• 404 DOMAIN_NOT_FOUND — the domain is not in your organization.
• 409 WEB_DOMAIN_CONFLICT — a web domain already occupies this hostname. See custom domains.
• 412 PRECONDITION_FAILED — receiving was never requested for this domain, or it was disabled. Call POST /channels/email/domains/{domainId}/receiving/request first, publish the MX record it gives you, then verify.
• 502 SENDGRID_ERROR — the mail provider call failed.

POST /channels/email/domains and POST /channels/email/domains/{domainId}/verify also answer 502 SENDGRID_ERROR when the provider call fails. A 502 is not a payload error. Retry with backoff, and do not change the request first.

ChangesCopy Anchor Link

• 2026-09-24 — POST /channels/email/domains returns the full email domain. The response now includes spfStatus, dkimStatus, mxStatus, receivingStatus, inboundParseConfiguredAt, verifiedAt, and createdAt. Before this change, the response had only id, domain, sendgridDomainId, and dnsRecords, although the published schema declared all eleven fields.