Edit a step

PATCH /api/v1/sequences/{sequenceId}/versions/{versionId}/nodes/{nodeId} Edits one node of a draft: subject, content, templateId, waitHours, sendTimeMinutes, tagId or webhookUrl. Send the fields of one family only — mixing a subject and a waitHours in the same call answers 400, and so does a body that carries nothing.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused — `403`

A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Path parameters

Parameter	Type	Description
`nodeId`	string	Required. The step to change

Request body

Field	Type	Required	Description
`subject` / `content`	string	no	On a `send_email` step
`preheader`	string	no	On a `send_email` step. Up to 200 characters, the preview text shown after the subject. Same family as `subject` and `content`, so it can be sent alone or with them
`waitHours`	number	no	On a `wait` step
`sendTimeMinutes`	number \| null	no	On a step of a series: the local time of day, in minutes from midnight (`540` = 09:00). `null` removes it, and the step then goes out as soon as the wait before it has elapsed. Its own family — send it alone, never alongside a subject or a content
`tagId`	string	no	On an `add_tag` / `remove_tag` step
`webhookUrl`	string	no	On a `webhook` step

Example

bash

curl -X PATCH -H "x-api-key: $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"waitHours": 48}' \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions/$VERSION_ID/nodes/$NODE_ID"

Response

200 OK — the call succeeded.
400 Bad Request — validation failed; 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.
404 Not Found — no such resource, 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

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`data.id`	string	Identifier of the step
`data.versionId`	string	The draft or published version it belongs to
`data.type`	string	`send_email`, `wait`, `add_tag`, `remove_tag`, `end_sequence`, `webhook`
`data.subject` / `content`	string \	null
`data.preheader`	string	Preview text of the step; empty string on a step that sends nothing
`data.templateId`	string \	null
`data.waitHours`	number \	null
`data.tagId`	string \	null
`data.webhookUrl`	string \	null
`data.createdAt` / `updatedAt`	string	ISO dates

Example response

json

{
  "success": true,
  "data": {
    "id": "4d19c0a2",
    "versionId": "c41a7e55",
    "type": "send_email",
    "subject` / `content": "value",
    "templateId": "5a44b901",
    "waitHours": 24,
    "tagId": "7c2ef4b1",
    "webhookUrl": "https://example.com/hooks/agentsmail",
    "createdAt` / `updatedAt": "value"
  }
}