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 update

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, or it waits for deletion.
• 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 reports the same missing connection as 412. Match on the error code and status.

Refusals on receiving verification

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.