---
title: "Change workflow mailing list"
method: POST
path: "/v1/workflows/{workflowId}/mailing-list"
tags: ["Workflows"]
---

# Change workflow mailing list

`POST /v1/workflows/{workflowId}/mailing-list`

Dry run or apply a workflow mailing list change. If queued contacts would be removed from the workflow due to the change of mailing list, Loops returns with `"status": "queuedContactsFound"` instead of applying the change. Retry with `queuedContactPolicy: "discard"` to apply the change and discard those contacts. Confirmed update responses include the simplified workflow after the mailing list changes.

## Request body

- ChangeWorkflowMailingListRequest
  - `expectedRevisionId` string, nullable, required — The workflow revision token returned by the latest workflow read or mutation. Older workflows may return `null` before their first revision-aware mutation; pass `null` back as `expectedRevisionId` in that case. If the token is stale, the API returns a `409 Conflict` error.
  - `mailingListId` string, nullable, required — The mailing list to use for the workflow. When assigning a mailing list, queued contacts excluded by the new list can return `queuedContactsFound`; retry with `queuedContactPolicy: "discard"` to apply the change and discard those contacts. Use `null` to clear the workflow mailing list; clearing does not discard queued contacts.
  - `dryRun` boolean — If `true`, the request will be validated but the workflow will not be modified.
  - `queuedContactPolicy` 'fail' | 'discard' — `fail` returns queued-contact impact instead of mutating. `discard` confirms that matching queued contacts should be discarded. Defaults to `fail` when omitted.

## Response `200`

Mailing-list dry run, queued-contact warning, or update result. Confirmed update responses include the simplified workflow after the mailing list changes.

- union
  - WorkflowMailingListPreview
    - `status` 'dryRun' | 'queuedContactsFound', required
    - `mailingListId` string, nullable, required
    - `queuedContactCount` number, required — The number of queued contacts that would be removed from the workflow due to the mailing list changing.
  - WorkflowMailingListUpdatedResponse
    - `status` 'updated', required
    - `mailingListId` string, nullable, required
    - `workflowRevisionId` string, required — The current workflow revision token. Pass the latest value as `expectedRevisionId` on the next workflow mutation.
    - `queuedContactCount` number, required — The number of queued contacts that were removed from the workflow due to the mailing list changing.
    - `workflow` SimplifiedWorkflow, required
      - `id` string, required — The ID of the workflow.
      - `url` string, uri, required — The URL of the workflow in the Loops app.
      - `workflowRevisionId` string, nullable, required — The current workflow revision token. Pass the latest value as `expectedRevisionId` on the next workflow mutation. Will be `null` for workflows without a revision token yet.
      - `status` 'Draft' | 'Sending' | 'Paused' | 'PausedAndQueueing', required
      - `name` string — The name of the workflow.
      - `description` string — The description of the workflow.
      - `mailingListId` string, nullable, required — The ID of the mailing list the workflow sends to.
      - `rootNodeId` string, required — The ID of the root node in the workflow graph.
      - `nodes` object, required — A map of node IDs to simplified node objects. Each node includes `typeName` and `nextNodeIds`, plus type-specific fields when present. To get the full node object, use the `GET /v1/workflows/{workflowId}/nodes/{nodeId}` endpoint.

## Other responses

- `400` — Invalid `workflowId`, request body, mailing list, or workflow state.
- `401` — Invalid API key.
- `404` — Workflow not found.
- `405` — Wrong HTTP request method.
- `409` — `expectedRevisionId` is stale.

## Changes

> 9 revisions in range; 1 not diffed.

- **2026-08-06** `96c4b50b8b95` — 1 info
  - added the required property `oneOf[#/components/schemas/WorkflowMailingListUpdatedResponse]/workflow` to the response with the `200` status
- **2026-07-26** `72d136d738c3` — 2 breaking
  - removed the required property `oneOf[#/components/schemas/WorkflowMailingListPreview]/queuedContactLimitReached` from the response with the `200` status
  - removed the required property `oneOf[#/components/schemas/WorkflowMailingListUpdatedResponse]/queuedContactLimitReached` from the response with the `200` status
- **2026-07-21** `df77516a130a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/loops/apis/loops-openapi-spec/changes/v1/workflows/:workflowId/mailing-list/post.md)

---

[API](https://skmtc.dev/loops/apis/loops-openapi-spec.md) · [All operations](https://skmtc.dev/loops/apis/loops-openapi-spec/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/loops/loops-openapi-spec/revisions/8bd0098300ec/schema)