Update a series

PATCH /api/v1/series/{seriesId} Two halves in one call, because the model puts them in two places: the name, topic and status live on the series, the start date and audience live on its version — so on its draft, never on a published version that sends already follow. Moving startsAt moves the whole series: no step carries a date of its own.

Authorization

RoleAccess
OWNERAllowed
ADMINAllowed
MEMBERRefused — 403

Path parameters

ParameterTypeDescription
seriesIdstring (uuid)The series id

Request body

Every field is optional; send only what changes.
FieldTypeRequiredDescription
namestringNo1 to 100 characters
statusstringNoactive or paused. Activating is refused until a version is published
topicIdstring (uuid) | nullNoIts editorial topic
startsAtstring (ISO 8601) | nullNoDay 1. Needs an open draft
listIdstring (uuid)NoThe list it sends to. Needs an open draft
audienceSegmentIdstring (uuid) | nullNoNeeds an open draft
audienceTagIdstring (uuid) | nullNoNeeds an open draft
json
{"startsAt": "2026-04-01T08:00:00.000Z"}

Example

bash
curl -s -X PATCH 'https://www.agentsmail.io/api/v1/series/7d7d7d7d-8888-4ccc-9ddd-eeee00001111' \
  -H "x-api-key: $AGENTMAIL_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"startsAt": "2026-04-01T08:00:00.000Z"}'

Response

CodeWhen
200The series as it now stands
400Invalid body, this id is not a series, or the calendar was touched with no draft open
401Missing or invalid key
403The key's role is MEMBER
404No series with this id in your organization

Response fields

Same shape as get a series.

Example response

json
{
  "success": true,
  "data": {
    "id": "7d7d7d7d-8888-4ccc-9ddd-eeee00001111",
    "name": "March launch",
    "status": "paused",
    "startsAt": "2026-04-01T08:00:00.000Z",
    "listId": "9f8e7d6c-1111-4bbb-8ccc-ddddeeeeffff",
    "audienceSegmentId": null,
    "audienceTagId": null,
    "topicId": null,
    "createdAt": "2026-03-01T10:00:00.000Z",
    "updatedAt": "2026-03-20T09:00:00.000Z"
  }
}

Notes

Changing the calendar needs an open draft. With none, the call answers 400 and changes nothing rather than opening one behind your back — opening a version is a deliberate act, and it has its own route: POST /api/v1/sequences/{seriesId}/versions. Publish afterwards for the change to take effect. The trigger is written whole. Fields you leave out keep the draft's current value, so moving the date alone never drops the audience you had set.

Related