Rename a topic

PATCH /api/v1/topics/{topicId} Changes the name of a topic. Nothing else moves: campaigns, sequences and recorded refusals all reference the id, so a rename is never a migration. A name already taken — case-insensitive — answers 409, exactly like creation.

Authorization

Role in the organizationThis endpoint
OWNERAllowed
ADMINAllowed
MEMBERRefused — 403
A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Path parameters

ParameterTypeDescription
topicIdstringRequired. The topic to rename

Request body

FieldTypeRequiredDescription
namestringyes1 to 50 characters
json
{"name": "agentic"}

Example

bash
curl -X PATCH -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"name":"agentic"}' \
  "https://www.agentsmail.io/api/v1/topics/$TOPIC_ID"

Response

  • 200 OK — the renamed topic.
  • 400 Bad Request — the name is missing, empty or over 50 characters; details carries the field-level issues.
  • 401 Unauthorized — missing or invalid key, or its owner left the organization.
  • 403 Forbidden — the key's owner is a member of the organization, not an admin.
  • 409 Conflict — another topic already carries that name, case ignored. Nothing was renamed.
  • 404 Not Found — no such topic, or it belongs to another organization. The API never confirms that an id exists to a caller who has no right to it.
  • 429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

FieldTypeDescription
successbooleanIndicates if the operation was successful
data.idstringUnique identifier for the topic
data.namestringIts new name
data.createdAtstringISO creation date
data.updatedAtstringISO date of the last change

Example response

json
{
  "success": true,
  "data": {
    "id": "7c2e4b19",
    "name": "agentic",
    "createdAt": "2026-03-04T08:11:00.000Z",
    "updatedAt": "2026-08-23T10:22:05.000Z"
  }
}

Notes

  • name is the only field this call takes. A topic has nothing else to change: attaching it is done from the campaign or the sequence, not from here.

Related