> ## Documentation Index
> Fetch the complete documentation index at: https://developer.mailbeast.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a subsequence

> Partial update - only what you pass changes. Each `settings` section (`trigger`, `start`, `sending`) and `sequence` REPLACE the current one. The emails of a running subsequence cannot be replaced - pause it first. Needs a plan with subsequences (Pro+ and above) - otherwise `403` with code `subsequences_plan_required`. `409 campaign_busy` = the campaign is being changed right now; retry in a few seconds.

Requires one of the following scopes: `campaigns:write`, `campaigns:all`, `all:all`.



## OpenAPI

````yaml /openapi.json patch /v1/subsequences/{id}
openapi: 3.0.0
info:
  title: MailBeast Public API
  description: >-
    Task-shaped REST API for campaigns, leads, deliverability, verification and
    lead discovery. Authenticate with an API key (`Authorization: Bearer
    mb_live_…`); the workspace is resolved from the key.
  version: '1'
  contact: {}
servers:
  - url: https://api.mailbeast.ai
security: []
tags:
  - name: API Keys
    description: Create, list and delete API keys programmatically.
  - name: Campaigns
    description: Create, configure, launch and monitor email campaigns.
  - name: Subsequences
    description: >-
      Follow-up flows of a campaign that start on a lead status, a reply, an
      open, a click or a finished sequence - from the same mailbox, in the same
      thread.
  - name: Leads
    description: Add, read, update and bulk-manage a campaign’s leads.
  - name: Workspace
    description: Read usage, subscription and workspace identity.
  - name: Email Accounts
    description: >-
      Connect and manage the sending mailboxes your campaigns send from
      (SMTP/IMAP or native OAuth).
  - name: Analytics
    description: Engagement reporting – per campaign, over time, and across the workspace.
  - name: Lead Finder
    description: >-
      Discover new companies and leads. List past searches and poll a running
      search’s progress.
paths:
  /v1/subsequences/{id}:
    patch:
      tags:
        - Subsequences
      summary: Update a subsequence
      description: >-
        Partial update - only what you pass changes. Each `settings` section
        (`trigger`, `start`, `sending`) and `sequence` REPLACE the current one.
        The emails of a running subsequence cannot be replaced - pause it first.
        Needs a plan with subsequences (Pro+ and above) - otherwise `403` with
        code `subsequences_plan_required`. `409 campaign_busy` = the campaign is
        being changed right now; retry in a few seconds.


        Requires one of the following scopes: `campaigns:write`,
        `campaigns:all`, `all:all`.
      operationId: subsequences_update
      parameters:
        - name: id
          required: true
          in: path
          description: Subsequence id.
          schema:
            type: string
            format: uuid
            example: 5b2f3c4d-6e7f-4a81-9b0c-1d2e3f4a5b6c
        - name: Idempotency-Key
          in: header
          description: >-
            Optional. A unique key you generate (max 255 chars, such as a UUID)
            that makes this request safe to retry. Retrying with the same key
            replays the original response instead of repeating the operation.
            Reusing a key with a different body returns `422`.
          required: false
          schema:
            type: string
            maxLength: 255
            example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubsequenceApiDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsequenceApiDto'
        '400':
          description: The request body or parameters failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorDto'
              example:
                error:
                  type: invalid_request_error
                  code: validation_failed
                  message: One or more fields are invalid.
                  status: 400
                  requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
                  details:
                    - name should not be empty
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorDto'
              example:
                error:
                  type: authentication_error
                  code: unauthenticated
                  message: Missing or invalid API key.
                  status: 401
                  requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
        '403':
          description: >-
            The key lacks a required scope, or the plan does not include API
            access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorDto'
              example:
                error:
                  type: authorization_error
                  code: permission_denied
                  message: This API key is missing the required scope.
                  status: 403
                  requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
        '404':
          description: The resource does not exist in your workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorDto'
              example:
                error:
                  type: invalid_request_error
                  code: not_found
                  message: Resource not found.
                  status: 404
                  requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
        '409':
          description: >-
            The request conflicts with current state - e.g. a request with the
            same Idempotency-Key is still being processed, or the operation
            partially applied.


            The request conflicts with current state - e.g. a request with the
            same Idempotency-Key is still being processed, or the operation
            partially applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorDto'
              example:
                error:
                  type: invalid_request_error
                  code: conflict
                  message: The request conflicts with an existing resource.
                  status: 409
                  requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
        '422':
          description: >-
            The Idempotency-Key was already used with a different request body.
            Use a new key for a new operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorDto'
              example:
                error:
                  type: invalid_request_error
                  code: idempotency_key_reused
                  message: >-
                    The Idempotency-Key was already used with a different
                    request body. Use a new key for a new operation.
                  status: 422
                  requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
        '429':
          description: >-
            Rate limit exceeded - retry after the interval in the Retry-After
            header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorDto'
              example:
                error:
                  type: rate_limit_error
                  code: rate_limited
                  message: >-
                    Too many requests. Retry after the interval in the
                    Retry-After header.
                  status: 429
                  requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
                  retryAfter: 30
      security:
        - ApiKey: []
components:
  schemas:
    UpdateSubsequenceApiDto:
      type: object
      properties:
        name:
          type: string
          example: Interested - book a call (v2)
          maxLength: 255
        settings:
          description: >-
            Trigger, start and sending settings. Each section you pass REPLACES
            that section as a whole (omitted sections keep their current value;
            on create, the defaults). Whether the subsequence is on is not a
            setting - use `/enable` and `/pause`. Every other setting
            (mailboxes, tracking, unsubscribe link, stop rules, verification
            skips) is inherited from the campaign and follows its changes.
          allOf:
            - $ref: '#/components/schemas/SubsequenceSettingsApiDto'
        sequence:
          minItems: 1
          maxItems: 20
          description: >-
            When supplied, REPLACES all emails of the subsequence (same rules as
            a campaign's `sequence`). A running subsequence's emails cannot be
            replaced - pause it first (400, nothing is written).
          type: array
          items:
            $ref: '#/components/schemas/SubsequenceSequenceStepApiDto'
        position:
          type: integer
          minimum: 1
          maximum: 10000
          example: 1
          description: >-
            Position among the subsequences of the campaign (1 = first). When
            one event matches several subsequences, the lead enters the first
            one.
    SubsequenceApiDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 5b2f3c4d-6e7f-4a81-9b0c-1d2e3f4a5b6c
        campaignId:
          type: string
          format: uuid
          example: a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60
          description: The campaign this subsequence belongs to.
        name:
          type: string
          example: Interested - book a call
        position:
          type: integer
          example: 1
          description: >-
            Order among the campaign's subsequences (1 = first): when one event
            matches several, the lead enters the first.
        status:
          type: string
          enum:
            - draft
            - scheduled
            - active
            - paused
            - stopped
            - completed
            - failed
          example: active
          description: >-
            Lifecycle status, same vocabulary as campaigns: `draft` / `paused` =
            off, `active` = on.
        enabled:
          type: boolean
          example: true
          description: >-
            Whether it is turned on (`/enable` / `/pause`). A subsequence of a
            draft campaign stays `draft` while on - it starts with the campaign.
        state:
          type: string
          enum:
            - draft
            - starts_with_campaign
            - active
            - paused
            - paused_with_campaign
            - stopped_campaign_ended
            - paused_requires_plan
            - cant_start
            - waiting_restart
          example: active
          description: >-
            Why it sends or not, in one word: `draft` - off;
            `starts_with_campaign` - on, starts when the draft campaign starts;
            `active` - on and sending; `paused` - paused by you;
            `paused_with_campaign` - on, but the campaign is paused;
            `stopped_campaign_ended` - the campaign completed, was stopped or
            deleted; `paused_requires_plan` - the plan does not include
            subsequences; `cant_start` - on, but it cannot start: it has no
            email, or an email is missing content; `waiting_restart` - on,
            waiting for the completed campaign to be restarted.
        settings:
          $ref: '#/components/schemas/SubsequenceSettingsView'
        sequence:
          description: >-
            The emails of the subsequence - the same shape as a campaign's
            `sequence`. A step with an empty `subject` replies in the same
            thread.
          type: array
          items:
            $ref: '#/components/schemas/CampaignSequenceStepView'
        counters:
          description: All-time counters (not limited to a period).
          allOf:
            - $ref: '#/components/schemas/SubsequenceCountersView'
        nextStartAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            When the next waiting lead gets its first email; null when nobody is
            waiting.
        createdAt:
          type: string
          format: date-time
          example: '2026-10-28T08:00:00.000Z'
      required:
        - id
        - campaignId
        - name
        - position
        - status
        - enabled
        - state
        - settings
        - sequence
        - counters
        - nextStartAt
        - createdAt
    ApiErrorDto:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorBodyDto'
      required:
        - error
    SubsequenceSettingsApiDto:
      type: object
      properties:
        trigger:
          description: 'Who enters. Default: no rules (manual only), listening to `main`.'
          allOf:
            - $ref: '#/components/schemas/SubsequenceTriggerApiDto'
        start:
          description: >-
            When the first email goes out after a lead enters. Default:
            `immediately`.
          allOf:
            - $ref: '#/components/schemas/SubsequenceStartApiDto'
        sending:
          description: 'Schedule and daily limit. Default: inherited from the campaign.'
          allOf:
            - $ref: '#/components/schemas/SubsequenceSendingApiDto'
    SubsequenceSequenceStepApiDto:
      type: object
      properties:
        subject:
          type: string
          example: ''
          maxLength: 500
          description: >-
            Subject. Leave it EMPTY ("") to reply in the same thread as the
            conversation with the lead (recommended for the first step); a
            subject of its own starts a new thread. Merge tags as in campaigns
            (snake_case, e.g. {{first_name}}). Required unless you pass
            `variants`.
        body:
          type: string
          example: '<p>Hi {{first_name}}, here is my calendar: …</p>'
          description: HTML body. Required unless you pass `variants`.
        variants:
          minItems: 1
          maxItems: 5
          description: >-
            A/B variants of this step, instead of `subject` + `body` - the same
            rules as campaign steps (up to 5, lettered A, B, C… in order, leads
            split evenly between the active ones).
          type: array
          items:
            $ref: '#/components/schemas/SubsequenceSequenceVariantApiDto'
        delayDays:
          type: integer
          example: 2
          minimum: 0
          maximum: 365
          description: >-
            Days to wait after the previous step. Must be 0 (or omitted) on the
            first step: when the first email goes out is set by
            `settings.start`. From step 2 on, `delayDays` + `delayHours` must
            add up to at least 1 hour.
        delayHours:
          type: integer
          example: 0
          minimum: 0
          maximum: 23
          description: >-
            Additional hours to wait after the previous step. Must be 0 (or
            omitted) on the first step.
    SubsequenceSettingsView:
      type: object
      properties:
        trigger:
          $ref: '#/components/schemas/SubsequenceTriggerApiDto'
        start:
          $ref: '#/components/schemas/SubsequenceStartApiDto'
        sending:
          $ref: '#/components/schemas/SubsequenceSendingApiDto'
      required:
        - trigger
        - start
        - sending
    CampaignSequenceStepView:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
        subject:
          type: string
          example: Quick question about {{company_name}}
          description: >-
            Subject of the first variant (a copy of `variants[0].subject`).
            Leave it out when you send the step back with `variants`.
        body:
          type: string
          example: <p>Hi {{first_name}}, …</p>
          description: >-
            Body of the first variant (a copy of `variants[0].body`). Leave it
            out when you send the step back with `variants`.
        delayDays:
          type: number
          example: 0
        delayHours:
          type: number
          example: 0
        variants:
          description: >-
            A/B variants of this step, by letter (A, B, C…). A step written with
            `subject` + `body` has a single variant `A`.
          type: array
          items:
            $ref: '#/components/schemas/CampaignSequenceVariantView'
      required:
        - id
        - subject
        - body
        - delayDays
        - delayHours
        - variants
    SubsequenceCountersView:
      type: object
      properties:
        entered:
          type: number
          example: 42
          description: Leads that ever entered.
        waiting:
          type: number
          example: 3
          description: >-
            Entered, first email scheduled for later (e.g. after an
            out-of-office return date).
        inProgress:
          type: number
          example: 12
          description: Currently in the subsequence (entered and not ended).
        replied:
          type: number
          example: 9
          description: Leads that replied to an email of the subsequence.
        positive:
          type: number
          example: 5
          description: >-
            Leads that replied and whose status in the subsequence is positive
            now (interested, meeting request, converted) — a subset of replied.
        ended:
          type: number
          example: 30
          description: >-
            Entries no longer in progress (all emails sent, replied, status
            changed, removed, moved to another subsequence…): entered =
            inProgress + ended.
      required:
        - entered
        - waiting
        - inProgress
        - replied
        - positive
        - ended
    ApiErrorBodyDto:
      type: object
      properties:
        type:
          type: string
          example: authorization_error
          description: Broad error class.
        code:
          type: string
          example: permission_denied
          description: Stable machine-readable code to switch on.
        message:
          type: string
          example: This API key is missing the required scope.
        status:
          type: number
          example: 403
        requestId:
          type: string
          example: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
          description: Correlation id - quote it in support requests.
        details:
          description: Field-level validation messages (present on validation errors).
          example:
            - name should not be empty
          type: array
          items:
            type: string
        retryAfter:
          type: number
          description: Seconds to wait before retrying (present on 429 responses).
          example: 30
      required:
        - type
        - code
        - message
        - status
        - requestId
    SubsequenceTriggerApiDto:
      type: object
      properties:
        any:
          maxItems: 5
          description: >-
            0-5 rules; ANY of them makes a lead enter. `[]` = manual only: leads
            enter only through `POST /v1/subsequences/{id}/leads` (or the
            dashboard).
          type: array
          items:
            $ref: '#/components/schemas/SubsequenceTriggerRuleApiDto'
        sources:
          example:
            - main
          description: >-
            Where the rules listen: `main` (the main sequence of the campaign)
            and/or ids of OTHER subsequences of the same campaign (e.g. a lead
            that replies "Interested" inside a re-engagement subsequence moves
            on to a "book a call" one). Always required: `[]` when `any` is
            empty, at least one source otherwise.
          type: array
          items:
            type: string
        filters:
          maxItems: 5
          description: 0-5 filters; a lead enters only if ALL of them match.
          type: array
          items:
            $ref: '#/components/schemas/SubsequenceFilterApiDto'
      required:
        - any
        - sources
        - filters
    SubsequenceStartApiDto:
      type: object
      properties:
        mode:
          type: string
          enum:
            - immediately
            - delay
            - ooo_return
          example: delay
          description: >-
            When the first email of the subsequence goes out after a lead
            enters: `immediately`, after a `delay` (`amount` + `unit`, up to 365
            days), or `ooo_return` - after the return date found in an
            out-of-office reply (only with a single `lead_status` rule for
            `lead_replied_out_of_office`). The first step has no delay of its
            own - this is it. Emails still go out only inside the sending
            schedule.
        amount:
          type: integer
          minimum: 1
          example: 1
          description: '`delay` only (required there).'
        unit:
          type: string
          enum:
            - minutes
            - hours
            - days
          example: hours
          description: '`delay` only (required there).'
        offsetDays:
          type: integer
          minimum: 0
          maximum: 30
          example: 1
          description: >-
            `ooo_return` only (required there): days after the return date (0 =
            on that day).
        withoutDate:
          description: '`ooo_return` only (required there).'
          allOf:
            - $ref: '#/components/schemas/SubsequenceOooWithoutDateApiDto'
        maxDaysAhead:
          type: integer
          nullable: true
          minimum: 1
          maximum: 730
          example: 120
          description: >-
            `ooo_return` only (required there): skip a lead that is away longer
            than this many days; `null` = no limit.
      required:
        - mode
    SubsequenceSendingApiDto:
      type: object
      properties:
        schedule:
          type: string
          enum:
            - inherit
            - custom
          example: inherit
          description: >-
            `inherit` - the campaign's sending schedule; `custom` - the
            subsequence keeps its own schedule (edited in the dashboard).
        dailyLimit:
          $ref: '#/components/schemas/SubsequenceDailyLimitApiDto'
      required:
        - schedule
        - dailyLimit
    SubsequenceSequenceVariantApiDto:
      type: object
      properties:
        subject:
          type: string
          example: ''
          maxLength: 500
          description: >-
            Subject. Leave it EMPTY ("") to reply in the same thread as the
            conversation with the lead (recommended for the first step); a
            subject of its own starts a new thread. Merge tags as in campaigns
            (snake_case, e.g. {{first_name}}).
        body:
          type: string
          example: '<p>Hi {{first_name}}, here is my calendar: …</p>'
          description: HTML body.
        isActive:
          type: boolean
          example: true
          default: true
          description: >-
            A switched-off variant is kept but not sent. At least one variant of
            each step must stay on.
      required:
        - subject
        - body
    CampaignSequenceVariantView:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: b3f1a2c4-5d6e-4f70-8a9b-0c1d2e3f4a5b
          description: >-
            Variant id. Pass it as `variantId` to POST
            /v1/campaigns/{id}/test-email.
        label:
          type: string
          example: A
          description: A/B variant letter.
        subject:
          type: string
          example: Quick question about {{company_name}}
        body:
          type: string
          example: <p>Hi {{first_name}}, …</p>
        isActive:
          type: boolean
          example: true
          description: >-
            Whether this variant is enabled. It is sent only while its step and
            the campaign are active too. Leads are split evenly between the
            enabled variants of a step; A/B auto-optimization switches the
            losing ones off.
      required:
        - id
        - label
        - subject
        - body
        - isActive
    SubsequenceTriggerRuleApiDto:
      type: object
      properties:
        kind:
          type: string
          enum:
            - lead_status
            - replied
            - reply_contains
            - opened
            - clicked
            - sequence_finished_no_reply
          example: lead_status
          description: >-
            What makes a lead enter. `lead_status` - its status became one of
            `statuses` (AI-classified reply or set by you); `replied` - any
            reply; `reply_contains` - a reply containing one of `phrases`;
            `opened` / `clicked` - an open / a click (needs tracking on the
            campaign), timed by `when`; `sequence_finished_no_reply` - the lead
            got every step of the main sequence and did not reply within
            `waitDays`. Each kind can be used once.
        statuses:
          type: array
          example:
            - lead_replied_interested
            - lead_replied_meeting_request
          description: >-
            `lead_status` only (required there): the statuses that make a lead
            enter.
          items:
            type: string
            enum:
              - lead_replied_interested
              - lead_replied_meeting_request
              - lead_replied_out_of_office
              - lead_replied_wrong_person
              - lead_replied_not_interested
              - lead_replied_uncategorized
              - lead_converted
              - lead_lost
        phrases:
          maxItems: 20
          example:
            - pricing
            - more info
          description: >-
            `reply_contains` only (required there): 1-20 phrases, 2-100
            characters each, matched case-insensitively.
          type: array
          items:
            type: string
        when:
          description: '`opened` and `clicked` only (required there): when the lead enters.'
          allOf:
            - $ref: '#/components/schemas/SubsequenceEngagementTimingApiDto'
        urlContains:
          type: string
          example: /pricing
          maxLength: 500
          description: >-
            `clicked` only (optional): count only clicks on links whose URL
            contains this text.
        waitDays:
          type: integer
          minimum: 0
          maximum: 60
          example: 3
          description: >-
            `sequence_finished_no_reply` only (required there): days to wait for
            a reply after the last email of the main sequence.
      required:
        - kind
    SubsequenceFilterApiDto:
      type: object
      properties:
        kind:
          type: string
          enum:
            - tag
            - custom_field
            - email_provider
            - engagement
            - replied
            - reached_step
          example: tag
          description: >-
            An extra condition every entering lead must meet (all filters must
            match). `tag` - lead tags (`op`: `has_any` / `has_none`, `values`);
            `custom_field` - a custom field (`field`, `op`: `equals` /
            `contains` / `is_empty` / `is_not_empty`, `value`); `email_provider`
            - `values` of `google` / `microsoft` / `other`; `engagement` - `op`:
            `opened_at_least` (with `emails`) / `not_opened` / `clicked` /
            `not_clicked`; `replied` - `value` true / false; `reached_step` -
            got at least step `atLeast` of the main sequence.
        op:
          type: string
          example: has_any
          description: Operator, see `kind`.
        values:
          example:
            - vip
          description: >-
            `tag` (tag names) and `email_provider` (`google` / `microsoft` /
            `other`).
          type: array
          items:
            type: string
        field:
          type: string
          example: industry
          description: '`custom_field`: the custom field name.'
        value:
          description: >-
            `custom_field` with `equals` / `contains`: the text to compare
            (required there). `replied`: true or false.
          oneOf:
            - type: string
            - type: boolean
        emails:
          type: integer
          minimum: 1
          maximum: 100
          description: '`engagement` with `opened_at_least`: number of emails opened.'
        atLeast:
          type: integer
          minimum: 1
          maximum: 50
          description: '`reached_step`: the step number.'
      required:
        - kind
    SubsequenceOooWithoutDateApiDto:
      type: object
      properties:
        mode:
          type: string
          enum:
            - delay
            - skip
          example: delay
          description: >-
            The auto-reply has no return date: start `days` after the auto-reply
            (`delay`) or do not enroll (`skip`).
        days:
          type: integer
          minimum: 1
          maximum: 90
          example: 7
          description: '`delay` only (required there).'
      required:
        - mode
    SubsequenceDailyLimitApiDto:
      type: object
      properties:
        mode:
          type: string
          enum:
            - inherit
            - custom
            - unlimited
          example: inherit
          description: >-
            `inherit` - the subsequence's emails count toward the campaign's
            daily limit and go out first, the campaign's own emails use the
            rest; `custom` - its own daily limit `value` on top of the
            campaign's; `unlimited` - only the mailboxes' own daily limits
            apply.
        value:
          type: integer
          minimum: 1
          maximum: 100000
          example: 30
          description: '`custom` only (required there).'
      required:
        - mode
    SubsequenceEngagementTimingApiDto:
      type: object
      properties:
        mode:
          type: string
          enum:
            - after_main_sequence
            - right_away
          example: after_main_sequence
          description: >-
            `after_main_sequence` (recommended): the lead finishes the main
            sequence first; if it did not reply but opened / clicked, it enters
            `waitDays` later. `right_away`: it enters at the open / click, and
            the rest of its main sequence is canceled.
        waitDays:
          type: integer
          minimum: 0
          maximum: 60
          example: 0
          description: >-
            Only with `after_main_sequence` (required there): days to wait after
            the main sequence ends.
      required:
        - mode
  securitySchemes:
    ApiKey:
      scheme: bearer
      bearerFormat: mb_live_…
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.