> ## 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. # Move leads into a subsequence > Move leads of the main campaign into the subsequence, by `leadIds` or `emails` (up to 1000). Their remaining main-sequence emails are canceled and the subsequence emails them instead (real email), from the same mailbox and in the same thread. Only leads that were already emailed can enter, each subsequence once, one subsequence at a time per lead; the response counts who entered and why the others did not. A subsequence that is off (paused or never turned on) takes them too: they wait and start when you turn it on. 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:lifecycle`, `campaigns:all`, `all:all`. ## OpenAPI ````yaml /openapi.json post /v1/subsequences/{id}/leads 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}/leads: post: tags: - Subsequences summary: Move leads into a subsequence description: >- Move leads of the main campaign into the subsequence, by `leadIds` or `emails` (up to 1000). Their remaining main-sequence emails are canceled and the subsequence emails them instead (real email), from the same mailbox and in the same thread. Only leads that were already emailed can enter, each subsequence once, one subsequence at a time per lead; the response counts who entered and why the others did not. A subsequence that is off (paused or never turned on) takes them too: they wait and start when you turn it on. 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:lifecycle`, `campaigns:all`, `all:all`. operationId: subsequences_enroll 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/EnrollSubsequenceLeadsApiDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/EnrollSubsequenceLeadsApiResponseDto' '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: EnrollSubsequenceLeadsApiDto: type: object properties: leadIds: maxItems: 1000 description: >- Lead ids of the MAIN campaign (`GET /v1/campaigns/{id}/leads`). Pass `leadIds` or `emails`, not both. example: - c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37 type: array items: type: string format: uuid emails: maxItems: 1000 description: >- Emails of leads of the MAIN campaign (case-insensitive). Pass `leadIds` or `emails`, not both. example: - jane@acme.com type: array items: type: string start: description: >- When the first email goes out. Default `{ "mode": "now" }`. Overrides the subsequence's `settings.start` for these leads. allOf: - $ref: '#/components/schemas/EnrollSubsequenceStartApiDto' EnrollSubsequenceLeadsApiResponseDto: type: object properties: enrolled: type: number example: 18 description: >- Leads that entered the subsequence (their remaining main-sequence emails are canceled). skipped: type: object additionalProperties: type: integer example: not_contacted: 2 already_enrolled: 1 description: >- Leads that did not enter, by reason: `not_contacted` (never emailed - a subsequence continues a conversation), `already_enrolled` (a lead enters each subsequence once), `suppressed` (unsubscribed, bounced or blacklisted), `company_replied` (a colleague at the same company replied in the campaign or one of its subsequences, and the campaign stops the company on a reply), `lead_removed`, `not_accepting` (the campaign is not active or paused - draft, completed, stopped or deleted -, the subsequence is completed or deleted, or the plan does not include subsequences; a subsequence that is paused or was never turned on still takes leads), `thread_unavailable` (step 1 replies in the same thread but the conversation's thread could not be found). Any other key also means the lead did not enter. notFound: type: number example: 0 description: Requested lead ids / emails that are not leads of the main campaign. required: - enrolled - skipped - notFound ApiErrorDto: type: object properties: error: $ref: '#/components/schemas/ApiErrorBodyDto' required: - error EnrollSubsequenceStartApiDto: type: object properties: mode: type: string enum: - now - delay - date example: now description: >- `now` - first email at the next sending window; `delay` - after `days` days; `date` - on `date` (YYYY-MM-DD, at the start of that day's sending window). days: type: integer minimum: 1 maximum: 365 example: 2 description: '`delay` only (required there).' date: type: string example: '2026-11-03' description: '`date` only (required there): YYYY-MM-DD in the schedule timezone.' required: - mode 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 securitySchemes: ApiKey: scheme: bearer bearerFormat: mb_live_… type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.