> ## Documentation Index > Fetch the complete documentation index at: https://docs.coldsend.pro/llms.txt > Use this file to discover all available pages before exploring further. # Create a subsequence > **Create a subsequence branch** A subsequence is a conditional branch off the MAIN follow-up chain: a trigger that pulls a lead out of the main path, plus an ordered chain of steps that then runs for that lead. Creating the first branch on a campaign sets `subsequences_enabled` to true automatically. ## Entry triggers `trigger_type` accepts **only** the three branch-entry triggers: - `INTENT_TAG` -- the lead was tagged with any of `trigger_params.tag_names` (a list of strings; the legacy single-value `tag_name` is still accepted). - `KEYWORD` -- a reply matched any of `trigger_params.phrases` (a list of strings). - `STATUS` -- the lead reached `trigger_params.status` (a string). `NOT_OPENED`, `NOT_REPLIED` and `OPENED_BUT_NOT_REPLIED` belong to the MAIN follow-up chain (`PUT /campaigns/{id}` with `sequences`) and are **rejected here** with a 422. `entry_from_node_id` is optional -- omit it and the campaign's root MAIN node is resolved for you. Pass it only to branch off a later step; get node ids from `GET /campaigns/{id}/flow`. ## Steps Each step needs `wait_seconds` (not `wait_days` as on the MAIN chain) and its `variants`. Leave `condition_type` alone: it defaults to `ALWAYS`, which is what a between-branch-steps timeout should be. A branch is entered *because* something happened, so a negative condition like `NOT_REPLIED` can never be satisfied inside one and such steps are silently discarded at send time. Variant objects use the wire field names: `subject`, `body`, `html_body`, `weight`. ## Response Returns the entry edge (whose `id` is the `subsequence_id` for later updates and deletes), the created nodes and the connecting edges. Nodes in this response carry no `variants` -- read the graph back with `GET /campaigns/{id}/flow` for content. ## Example Usage ```python import requests campaign_id = "550e8400-e29b-41d4-a716-446655440000" response = requests.post( f"https://api.coldsend.pro/api/public/v1/campaigns/{campaign_id}/flow/subsequences", headers={"X-API-Key": "your-api-key"}, json={ "label": "Interested - nurture", "trigger_type": "INTENT_TAG", "trigger_params": {"tag_names": ["interested", "asked_for_demo"]}, "priority": 10, "steps": [ { "wait_seconds": 3600, "label": "Send case study", "variants": [{ "variant_name": "A", "subject": "The case study you asked for", "body": "Here it is -- {{firstName}}, thought you'd like this.", "weight": 100 }] }, { "wait_seconds": 259200, "label": "Check in", "variants": [{ "variant_name": "A", "subject": "Any thoughts?", "body": "Did the case study answer your questions?", "weight": 100 }] } ] } ) print(response.json()) ``` ## OpenAPI ````yaml /public_openapi.json post /api/public/v1/campaigns/{campaign_id}/flow/subsequences openapi: 3.0.3 info: title: ColdSend Public API description: >- Programmatic access to ColdSend for managing cold email campaigns and sender accounts. version: 1.0.0 contact: name: ColdSend Support email: support@coldsend.pro url: https://coldsend.pro servers: - url: https://api.coldsend.pro description: Production security: - ApiKeyAuth: [] paths: /api/public/v1/campaigns/{campaign_id}/flow/subsequences: post: tags: - Flow summary: Create a subsequence description: >- **Create a subsequence branch** A subsequence is a conditional branch off the MAIN follow-up chain: a trigger that pulls a lead out of the main path, plus an ordered chain of steps that then runs for that lead. Creating the first branch on a campaign sets `subsequences_enabled` to true automatically. ## Entry triggers `trigger_type` accepts **only** the three branch-entry triggers: - `INTENT_TAG` -- the lead was tagged with any of `trigger_params.tag_names` (a list of strings; the legacy single-value `tag_name` is still accepted). - `KEYWORD` -- a reply matched any of `trigger_params.phrases` (a list of strings). - `STATUS` -- the lead reached `trigger_params.status` (a string). `NOT_OPENED`, `NOT_REPLIED` and `OPENED_BUT_NOT_REPLIED` belong to the MAIN follow-up chain (`PUT /campaigns/{id}` with `sequences`) and are **rejected here** with a 422. `entry_from_node_id` is optional -- omit it and the campaign's root MAIN node is resolved for you. Pass it only to branch off a later step; get node ids from `GET /campaigns/{id}/flow`. ## Steps Each step needs `wait_seconds` (not `wait_days` as on the MAIN chain) and its `variants`. Leave `condition_type` alone: it defaults to `ALWAYS`, which is what a between-branch-steps timeout should be. A branch is entered *because* something happened, so a negative condition like `NOT_REPLIED` can never be satisfied inside one and such steps are silently discarded at send time. Variant objects use the wire field names: `subject`, `body`, `html_body`, `weight`. ## Response Returns the entry edge (whose `id` is the `subsequence_id` for later updates and deletes), the created nodes and the connecting edges. Nodes in this response carry no `variants` -- read the graph back with `GET /campaigns/{id}/flow` for content. ## Example Usage ```python import requests campaign_id = "550e8400-e29b-41d4-a716-446655440000" response = requests.post( f"https://api.coldsend.pro/api/public/v1/campaigns/{campaign_id}/flow/subsequences", headers={"X-API-Key": "your-api-key"}, json={ "label": "Interested - nurture", "trigger_type": "INTENT_TAG", "trigger_params": {"tag_names": ["interested", "asked_for_demo"]}, "priority": 10, "steps": [ { "wait_seconds": 3600, "label": "Send case study", "variants": [{ "variant_name": "A", "subject": "The case study you asked for", "body": "Here it is -- {{firstName}}, thought you'd like this.", "weight": 100 }] }, { "wait_seconds": 259200, "label": "Check in", "variants": [{ "variant_name": "A", "subject": "Any thoughts?", "body": "Did the case study answer your questions?", "weight": 100 }] } ] } ) print(response.json()) ``` operationId: >- create_subsequence_api_public_v1_campaigns__campaign_id__flow_subsequences_post parameters: - name: campaign_id in: path required: true schema: type: string format: uuid title: Campaign Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubsequenceCreate' responses: '201': description: Subsequence created content: application/json: schema: $ref: '#/components/schemas/SubsequenceResponse' '400': description: Validation failed - see detail message '401': description: Missing or invalid API key '403': description: Insufficient permissions - requires 'campaigns:update' scope '404': description: Campaign not found in this team '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: SubsequenceCreate: properties: trigger_type: type: string title: Trigger Type description: 'Entry trigger type: INTENT_TAG, KEYWORD, or STATUS' trigger_params: additionalProperties: true type: object nullable: true title: Trigger Params description: >- Trigger parameters. INTENT_TAG takes tag_names: list[str] (the legacy single-value tag_name: str is still accepted); KEYWORD takes phrases: list[str]; STATUS takes status: str. entry_from_node_id: type: string format: uuid nullable: true title: Entry From Node Id description: MAIN node that triggers entry; auto-resolved when omitted priority: type: integer title: Priority description: Priority of the entry EVENT edge default: 0 steps: items: $ref: '#/components/schemas/SubsequenceStepCreate' type: array minItems: 1 title: Steps description: Ordered list of subsequence steps label: type: string maxLength: 255 nullable: true title: Label description: Subsequence label type: object required: - trigger_type - steps title: SubsequenceCreate description: |- Convenience request to create a full subsequence branch. Bundles the entry condition (trigger type + params + priority) with a list of steps that form a linear chain of SUBSEQUENCE EMAIL nodes connected by TIMEOUT edges. SubsequenceResponse: properties: entry_edge: $ref: '#/components/schemas/FlowEdgeResponse' nodes: items: $ref: '#/components/schemas/FlowNodeResponse' type: array title: Nodes edges: items: $ref: '#/components/schemas/FlowEdgeResponse' type: array title: Edges type: object required: - entry_edge - nodes - edges title: SubsequenceResponse description: Response for a created/updated subsequence (entry edge + nodes). HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SubsequenceStepCreate: properties: wait_seconds: type: integer minimum: 0 title: Wait Seconds description: Seconds before this step fires condition_type: type: string title: Condition Type description: Timeout condition between steps default: ALWAYS label: type: string maxLength: 255 nullable: true title: Label variants: items: additionalProperties: true type: object type: array nullable: true title: Variants description: Email variant data for this step node type: object required: - wait_seconds title: SubsequenceStepCreate description: A single step within a subsequence creation request. FlowEdgeResponse: properties: id: type: string format: uuid title: Id campaign_id: type: string format: uuid title: Campaign Id from_node_id: type: string format: uuid title: From Node Id to_node_id: type: string format: uuid title: To Node Id kind: type: string title: Kind condition_type: type: string title: Condition Type condition_params: additionalProperties: true type: object nullable: true title: Condition Params wait_seconds: type: integer nullable: true title: Wait Seconds priority: type: integer title: Priority is_active: type: boolean title: Is Active created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At type: object required: - id - campaign_id - from_node_id - to_node_id - kind - condition_type - priority - is_active - created_at - updated_at title: FlowEdgeResponse description: Response for a single flow edge. FlowNodeResponse: properties: id: type: string format: uuid title: Id campaign_id: type: string format: uuid title: Campaign Id node_type: type: string title: Node Type node_group: type: string title: Node Group label: type: string nullable: true title: Label position: additionalProperties: true type: object nullable: true title: Position created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At variants: items: $ref: '#/components/schemas/FlowNodeVariantResponse' type: array nullable: true title: Variants type: object required: - id - campaign_id - node_type - node_group - created_at - updated_at title: FlowNodeResponse description: Response for a single flow node. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError FlowNodeVariantResponse: properties: variant_name: type: string title: Variant Name variant_label: type: string nullable: true title: Variant Label subject: type: string nullable: true title: Subject body: type: string nullable: true title: Body html_body: type: string nullable: true title: Html Body weight: type: integer title: Weight default: 100 content_type: type: string nullable: true title: Content Type type: object required: - variant_name title: FlowNodeVariantResponse description: >- Email content stored against a SUBSEQUENCE node. Field names mirror the write side (``SubsequenceStepCreate.variants``) so a client can round-trip a branch step without translating: ``subject`` / ``body`` / ``html_body`` / ``weight`` on the wire, ``subject_template`` / ``body_template`` / ``html_template`` / ``distribution_percent`` in the column. ``_VARIANT_FIELD_MAP`` in services/flow_service.py owns the write direction of the same mapping. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key with format cs_live_xxx ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.