# Channels

## List SES setups

> Paginated list of every SES setup on the platform. Items carry the cached \`\`dns\_verified\`\` aggregate; call \`\`GET /ses-setup/{id}\`\` for per-record DNS detail. Setups are shared platform-wide; any caller with \`\`Channel.view\`\` permission sees the full list.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PaginatedResponse_SesSetupListItemResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SesSetupListItemResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[SesSetupListItemResponse]"},"SesSetupListItemResponse":{"properties":{"id":{"type":"string","title":"Id"},"tenant_name":{"type":"string","title":"Tenant Name"},"domain_identity":{"type":"string","title":"Domain Identity"},"dns_verified":{"type":"boolean","title":"Dns Verified","description":"Aggregate of every DNS record's ``verified`` at the last refresh."},"dns_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Dns Checked At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","tenant_name","domain_identity","dns_verified","dns_checked_at","created_at","updated_at"],"title":"SesSetupListItemResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/channels/ses-setup":{"get":{"tags":["Channels"],"summary":"List SES setups","description":"Paginated list of every SES setup on the platform. Items carry the cached ``dns_verified`` aggregate; call ``GET /ses-setup/{id}`` for per-record DNS detail. Setups are shared platform-wide; any caller with ``Channel.view`` permission sees the full list.","operationId":"list-ses-setups","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"exclusiveMinimum":0,"default":10,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_SesSetupListItemResponse_"}}}},"403":{"description":"Insufficient permissions."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create an SES setup

> Create an SES tenant + verified email identity. Returns the DNS records the customer must publish (DKIM CNAMEs, MX, DMARC TXT). Subsequent \`\`GET\`\` or \`\`POST /verify\`\` calls re-run the live DNS lookup and update the per-record \`\`verified\`\` flag. Setups are shared platform-wide; any caller with \`\`Channel.create\`\` permission can create one.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CreateSesSetupRequest":{"properties":{"tenant_name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9_-]+$","title":"Tenant Name","description":"Logical SES tenant name (reputation + suppression isolation boundary).\nUnique within the AWS account. Alphabet ``[A-Za-z0-9_-]``, 1-64 chars."},"domain_identity":{"type":"string","maxLength":255,"minLength":1,"title":"Domain Identity","description":"Domain to verify for both sending and receiving (e.g.\n``mail.customer.com``). A single SES identity serves both directions."}},"type":"object","required":["tenant_name","domain_identity"],"title":"CreateSesSetupRequest"},"SesSetupDetailResponse":{"properties":{"id":{"type":"string","title":"Id"},"tenant_name":{"type":"string","title":"Tenant Name"},"domain_identity":{"type":"string","title":"Domain Identity"},"dns_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Dns Checked At"},"dns_records":{"items":{"$ref":"#/components/schemas/DnsRecordResponse"},"type":"array","title":"Dns Records"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","tenant_name","domain_identity","dns_checked_at","dns_records","created_at","updated_at"],"title":"SesSetupDetailResponse"},"DnsRecordResponse":{"properties":{"address":{"type":"string","title":"Address","description":"Fully-qualified hostname the DNS entry lives under."},"record":{"type":"string","title":"Record","description":"Target value the customer must publish at their DNS provider."},"type":{"type":"string","enum":["CNAME","MX","TXT"],"title":"Type"},"verified":{"type":"boolean","title":"Verified","description":"Whether the live DNS lookup at the time of the GET found the entry."}},"type":"object","required":["address","record","type","verified"],"title":"DnsRecordResponse"}}},"paths":{"/v1/{workspace_id}/channels/ses-setup":{"post":{"tags":["Channels"],"summary":"Create an SES setup","description":"Create an SES tenant + verified email identity. Returns the DNS records the customer must publish (DKIM CNAMEs, MX, DMARC TXT). Subsequent ``GET`` or ``POST /verify`` calls re-run the live DNS lookup and update the per-record ``verified`` flag. Setups are shared platform-wide; any caller with ``Channel.create`` permission can create one.","operationId":"create-ses-setup","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSesSetupRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SesSetupDetailResponse"}}}},"403":{"description":"Insufficient permissions."},"409":{"description":"Tenant name or domain identity already exists upstream."},"422":{"description":"Invalid SES setup configuration."},"502":{"description":"Channel manager unavailable."},"504":{"description":"Channel manager timed out."}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Get an SES setup with live DNS refresh

> Returns full SES setup detail including per-record DNS verification status. Channel-manager re-runs \`\`GetEmailIdentity\`\` + DMARC/MX resolvers on every call, so each GET is a live check. Requires \`\`Channel.view\`\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SesSetupDetailResponse":{"properties":{"id":{"type":"string","title":"Id"},"tenant_name":{"type":"string","title":"Tenant Name"},"domain_identity":{"type":"string","title":"Domain Identity"},"dns_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Dns Checked At"},"dns_records":{"items":{"$ref":"#/components/schemas/DnsRecordResponse"},"type":"array","title":"Dns Records"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","tenant_name","domain_identity","dns_checked_at","dns_records","created_at","updated_at"],"title":"SesSetupDetailResponse"},"DnsRecordResponse":{"properties":{"address":{"type":"string","title":"Address","description":"Fully-qualified hostname the DNS entry lives under."},"record":{"type":"string","title":"Record","description":"Target value the customer must publish at their DNS provider."},"type":{"type":"string","enum":["CNAME","MX","TXT"],"title":"Type"},"verified":{"type":"boolean","title":"Verified","description":"Whether the live DNS lookup at the time of the GET found the entry."}},"type":"object","required":["address","record","type","verified"],"title":"DnsRecordResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/channels/ses-setup/{setup_id}":{"get":{"tags":["Channels"],"summary":"Get an SES setup with live DNS refresh","description":"Returns full SES setup detail including per-record DNS verification status. Channel-manager re-runs ``GetEmailIdentity`` + DMARC/MX resolvers on every call, so each GET is a live check. Requires ``Channel.view`` permission.","operationId":"get-ses-setup","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"setup_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Setup Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SesSetupDetailResponse"}}}},"403":{"description":"Insufficient permissions."},"404":{"description":"SES setup not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete an SES setup

> Tear down the upstream SES tenant + identity. Refuses (409) if any use case still references the setup. Requires \`\`Channel.delete\`\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/channels/ses-setup/{setup_id}":{"delete":{"tags":["Channels"],"summary":"Delete an SES setup","description":"Tear down the upstream SES tenant + identity. Refuses (409) if any use case still references the setup. Requires ``Channel.delete`` permission.","operationId":"delete-ses-setup","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"setup_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Setup Id"}}],"responses":{"204":{"description":"Successful Response"},"403":{"description":"Insufficient permissions."},"404":{"description":"SES setup not found."},"409":{"description":"Setup still referenced by live use cases."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"502":{"description":"Channel manager unavailable."},"504":{"description":"Channel manager timed out."}}}}}}
```

## Refresh SES DNS verification

> Explicit DNS refresh endpoint. Equivalent to \`\`GET /ses-setup/{id}\`\` but exposed as a POST so UI \`\`Verify now\`\` actions read as actions rather than reads. Requires \`\`Channel.view\`\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SesSetupDetailResponse":{"properties":{"id":{"type":"string","title":"Id"},"tenant_name":{"type":"string","title":"Tenant Name"},"domain_identity":{"type":"string","title":"Domain Identity"},"dns_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Dns Checked At"},"dns_records":{"items":{"$ref":"#/components/schemas/DnsRecordResponse"},"type":"array","title":"Dns Records"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","tenant_name","domain_identity","dns_checked_at","dns_records","created_at","updated_at"],"title":"SesSetupDetailResponse"},"DnsRecordResponse":{"properties":{"address":{"type":"string","title":"Address","description":"Fully-qualified hostname the DNS entry lives under."},"record":{"type":"string","title":"Record","description":"Target value the customer must publish at their DNS provider."},"type":{"type":"string","enum":["CNAME","MX","TXT"],"title":"Type"},"verified":{"type":"boolean","title":"Verified","description":"Whether the live DNS lookup at the time of the GET found the entry."}},"type":"object","required":["address","record","type","verified"],"title":"DnsRecordResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/channels/ses-setup/{setup_id}/verify":{"post":{"tags":["Channels"],"summary":"Refresh SES DNS verification","description":"Explicit DNS refresh endpoint. Equivalent to ``GET /ses-setup/{id}`` but exposed as a POST so UI ``Verify now`` actions read as actions rather than reads. Requires ``Channel.view`` permission.","operationId":"verify-ses-setup-dns","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"setup_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Setup Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SesSetupDetailResponse"}}}},"403":{"description":"Insufficient permissions."},"404":{"description":"SES setup not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/channels.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.