{
"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"
]
}
}
{
"error": {
"type": "authentication_error",
"code": "unauthenticated",
"message": "Missing or invalid API key.",
"status": 401,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"
}
}
{
"error": {
"type": "authorization_error",
"code": "permission_denied",
"message": "This API key is missing the required scope.",
"status": 403,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"
}
}
{
"error": {
"type": "invalid_request_error",
"code": "conflict",
"message": "The request conflicts with an existing resource.",
"status": 409,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"
}
}
{
"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"
}
}
{
"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
}
}
Subsequences
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.
{
"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"
]
}
}
{
"error": {
"type": "authentication_error",
"code": "unauthenticated",
"message": "Missing or invalid API key.",
"status": 401,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"
}
}
{
"error": {
"type": "authorization_error",
"code": "permission_denied",
"message": "This API key is missing the required scope.",
"status": 403,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"
}
}
{
"error": {
"type": "invalid_request_error",
"code": "conflict",
"message": "The request conflicts with an existing resource.",
"status": 409,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"
}
}
{
"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"
}
}
{
"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
}
}
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.
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.
Requested lead ids / emails that are not leads of the main campaign.
Example:
0
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"MailBeast API","description":"Task-shaped REST API for cold email at scale - campaigns, leads, deliverability, verification and lead discovery.","colors":{"primary":"#2F62E8","light":"#5D8DF6","dark":"#1E46B0"},"logo":{"light":"https://mintcdn.com/mail-beast-ai/wTQEP6MPos1XZJQD/logo/light.svg?fit=max\u0026auto=format\u0026n=wTQEP6MPos1XZJQD\u0026q=85\u0026s=aeac906ba6340f321596e4d877c72bf1","dark":"https://mintcdn.com/mail-beast-ai/wTQEP6MPos1XZJQD/logo/dark.svg?fit=max\u0026auto=format\u0026n=wTQEP6MPos1XZJQD\u0026q=85\u0026s=d545596dc15a153ea80a91602ce3bf0c"},"favicon":"https://mintcdn.com/mail-beast-ai/wTQEP6MPos1XZJQD/favicon.png?fit=max\u0026auto=format\u0026n=wTQEP6MPos1XZJQD\u0026q=85\u0026s=375d802479a055444b3bbd6544d40be9","navbar":{"primary":{"type":"button","label":"Dashboard","href":"https://app.mailbeast.ai"}},"footer":{"socials":{"website":"https://mailbeast.ai"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"mail-beast-ai","hasAudioNarration":false,"actualSubdomain":"mail-beast-ai","customDomains":["developer.mailbeast.ai"],"gitSource":{"type":"github","owner":"mark-digital-llc","repo":"mailbeast-api-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"collectionId":"34e7e6f5-e541-42d2-b00f-861b90431fc7","liveDeploymentHistoryId":"6aeb94b3ddb30f355ee1d1ac","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6aeb94b3ddb30f355ee1d1ac"},"feedback":{"agentFeedback":true},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6aeb94b3ddb30f355ee1d1ac","clientVersion":"0.0.4067","searchFilterCounts":[{"language":"default","tag":"API Reference","count":55},{"language":"default","tag":"Guides","count":13},{"language":"default","tag":"Email Accounts","count":11},{"language":"default","tag":"Campaigns","count":10},{"language":"default","tag":"Subsequences","count":9},{"language":"default","tag":"Resources","count":8},{"language":"default","tag":"Leads","count":7},{"language":"default","tag":"Emails","count":6},{"language":"default","tag":"Get started","count":5},{"language":"default","tag":"Workspace","count":4}],"searchSettings":{"showContentSnippets":false}},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/subsequences/move-leads-into-a-subsequence","slug":"/api-reference/subsequences/move-leads-into-a-subsequence","pageMetadata":{"title":"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.\n\nRequires one of the following scopes: `campaigns:lifecycle`, `campaigns:all`, `all:all`.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/subsequences/{id}/leads","href":"/api-reference/subsequences/move-leads-into-a-subsequence","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Move leads of the main campaign into the subsequence, by \", _jsx(_components.code, {\n children: \"leadIds\"\n }), \" or \", _jsx(_components.code, {\n children: \"emails\"\n }), \" (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 \", _jsx(_components.code, {\n children: \"403\"\n }), \" with code \", _jsx(_components.code, {\n children: \"subsequences_plan_required\"\n }), \". \", _jsx(_components.code, {\n children: \"409 campaign_busy\"\n }), \" = the campaign is being changed right now; retry in a few seconds.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Requires one of the following scopes: \", _jsx(_components.code, {\n children: \"campaigns:lifecycle\"\n }), \", \", _jsx(_components.code, {\n children: \"campaigns:all\"\n }), \", \", _jsx(_components.code, {\n children: \"all:all\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"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.\n\nRequires one of the following scopes: `campaigns:lifecycle`, `campaigns:all`, `all:all`.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/subsequences/{id}/leads","href":"/api-reference/subsequences/move-leads-into-a-subsequence","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"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.\n\nRequires one of the following scopes: `campaigns:lifecycle`, `campaigns:all`, `all:all`.","operationId":"subsequences_enroll","parameters":["69a23546-5557-4d38-80aa-6fb7b4626dc2","81dfb5f1-7164-4d22-a1d3-4cd5c7c0bbcc"],"requestBody":"664e18db-b47e-4517-8a3a-bfa07ad8b92d","responses":{"200":"817ffec1-90eb-4fb8-8b9b-319bfe42d23c","400":"495d4245-542e-4f39-b586-db3123a4db48","401":"1bc845fc-167c-4844-b30b-f704294d7085","403":"671e1b94-7ae9-41e2-9b1c-0b8e37021c4f","404":"11cd7bfd-8e4c-43d0-82ac-bed028f74f58","409":"e7f32cee-738d-46dd-ad2b-a20e74839fd1","422":"0398ebb3-a992-4154-9a25-649730ebb0c5","429":"c06ecfc2-8827-4df2-bcc9-25983dc8a3ae"},"security":["e530ccb3-9543-4396-bc5d-fb05e7b0155d"],"summary":"Move leads into a subsequence","tags":["Subsequences"],"method":"post","type":"path","servers":["e914a309-44fa-4a4c-b571-a32c0fb4ed0a"],"path":"/v1/subsequences/{id}/leads","baseUrlOptions":["https://api.mailbeast.ai"],"title":"Move leads into a subsequence","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"69a23546-5557-4d38-80aa-6fb7b4626dc2":{"name":"id","required":true,"in":"path","description":"Subsequence id.","schema":{"type":"string","format":"uuid","example":"5b2f3c4d-6e7f-4a81-9b0c-1d2e3f4a5b6c","isRequired":true,"description":"Subsequence id.","uniqueKey":"","typeLabel":"string\u003cuuid>"}},"81dfb5f1-7164-4d22-a1d3-4cd5c7c0bbcc":{"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","isRequired":false,"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`.","uniqueKey":"","typeLabel":"string"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"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","uniqueKey":"leadIds.items.[INDEX]","typeLabel":"string\u003cuuid>"},"uniqueKey":"leadIds","typeLabel":"string\u003cuuid>[]"},"emails":{"maxItems":1000,"description":"Emails of leads of the MAIN campaign (case-insensitive). Pass `leadIds` or `emails`, not both.","example":["[email protected]"],"type":"array","items":{"type":"string","uniqueKey":"emails.items.[INDEX]","typeLabel":"string"},"uniqueKey":"emails","typeLabel":"string[]"},"start":{"type":"object","description":"When the first email goes out. Default `{ \"mode\": \"now\" }`. Overrides the subsequence's `settings.start` for these leads.","required":["mode"],"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).","isRequired":true,"uniqueKey":"start.mode","typeLabel":"enum\u003cstring>"},"days":{"type":"integer","minimum":1,"maximum":365,"example":2,"description":"`delay` only (required there).","uniqueKey":"start.days","typeLabel":"integer"},"date":{"type":"string","example":"2026-11-03","description":"`date` only (required there): YYYY-MM-DD in the schedule timezone.","uniqueKey":"start.date","typeLabel":"string"}},"uniqueKey":"start","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"leadIds":["c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37"],"emails":["[email protected]"]}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"817ffec1-90eb-4fb8-8b9b-319bfe42d23c":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"enrolled":{"type":"number","example":18,"description":"Leads that entered the subsequence (their remaining main-sequence emails are canceled).","isRequired":true,"uniqueKey":"enrolled","typeLabel":"number"},"skipped":{"type":"object","additionalProperties":{"type":"integer","uniqueKey":"skipped.additionalProperties","typeLabel":"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.","isRequired":true,"uniqueKey":"skipped","typeLabel":"object"},"notFound":{"type":"number","example":0,"description":"Requested lead ids / emails that are not leads of the main campaign.","isRequired":true,"uniqueKey":"notFound","typeLabel":"number"}},"required":["enrolled","skipped","notFound"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"enrolled":18,"skipped":{"not_contacted":2,"already_enrolled":1},"notFound":0}}},"exampleType":"generated"}},"exampleType":"generated"},"495d4245-542e-4f39-b586-db3123a4db48":{"description":"The request body or parameters failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"authorization_error","description":"Broad error class.","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"code":{"type":"string","example":"permission_denied","description":"Stable machine-readable code to switch on.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","example":"This API key is missing the required scope.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"status":{"type":"number","example":403,"isRequired":true,"uniqueKey":"error.status","typeLabel":"number"},"requestId":{"type":"string","example":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f","description":"Correlation id - quote it in support requests.","isRequired":true,"uniqueKey":"error.requestId","typeLabel":"string"},"details":{"description":"Field-level validation messages (present on validation errors).","example":["name should not be empty"],"type":"array","items":{"type":"string","uniqueKey":"error.details.items.[INDEX]","typeLabel":"string"},"uniqueKey":"error.details","typeLabel":"string[]"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying (present on 429 responses).","example":30,"uniqueKey":"error.retryAfter","typeLabel":"number"}},"required":["type","code","message","status","requestId"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"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"]}},"examples":{"Example":{"title":"Example","value":{"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"]}}}},"exampleType":"examples"}},"exampleType":"examples"},"1bc845fc-167c-4844-b30b-f704294d7085":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"authorization_error","description":"Broad error class.","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"code":{"type":"string","example":"permission_denied","description":"Stable machine-readable code to switch on.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","example":"This API key is missing the required scope.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"status":{"type":"number","example":403,"isRequired":true,"uniqueKey":"error.status","typeLabel":"number"},"requestId":{"type":"string","example":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f","description":"Correlation id - quote it in support requests.","isRequired":true,"uniqueKey":"error.requestId","typeLabel":"string"},"details":{"description":"Field-level validation messages (present on validation errors).","example":["name should not be empty"],"type":"array","items":{"type":"string","uniqueKey":"error.details.items.[INDEX]","typeLabel":"string"},"uniqueKey":"error.details","typeLabel":"string[]"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying (present on 429 responses).","example":30,"uniqueKey":"error.retryAfter","typeLabel":"number"}},"required":["type","code","message","status","requestId"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"example":{"error":{"type":"authentication_error","code":"unauthenticated","message":"Missing or invalid API key.","status":401,"requestId":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"}},"examples":{"Example":{"title":"Example","value":{"error":{"type":"authentication_error","code":"unauthenticated","message":"Missing or invalid API key.","status":401,"requestId":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"}}}},"exampleType":"examples"}},"exampleType":"examples"},"671e1b94-7ae9-41e2-9b1c-0b8e37021c4f":{"description":"The key lacks a required scope, or the plan does not include API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"authorization_error","description":"Broad error class.","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"code":{"type":"string","example":"permission_denied","description":"Stable machine-readable code to switch on.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","example":"This API key is missing the required scope.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"status":{"type":"number","example":403,"isRequired":true,"uniqueKey":"error.status","typeLabel":"number"},"requestId":{"type":"string","example":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f","description":"Correlation id - quote it in support requests.","isRequired":true,"uniqueKey":"error.requestId","typeLabel":"string"},"details":{"description":"Field-level validation messages (present on validation errors).","example":["name should not be empty"],"type":"array","items":{"type":"string","uniqueKey":"error.details.items.[INDEX]","typeLabel":"string"},"uniqueKey":"error.details","typeLabel":"string[]"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying (present on 429 responses).","example":30,"uniqueKey":"error.retryAfter","typeLabel":"number"}},"required":["type","code","message","status","requestId"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"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"}},"examples":{"Example":{"title":"Example","value":{"error":{"type":"authorization_error","code":"permission_denied","message":"This API key is missing the required scope.","status":403,"requestId":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"}}}},"exampleType":"examples"}},"exampleType":"examples"},"11cd7bfd-8e4c-43d0-82ac-bed028f74f58":{"description":"The resource does not exist in your workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"authorization_error","description":"Broad error class.","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"code":{"type":"string","example":"permission_denied","description":"Stable machine-readable code to switch on.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","example":"This API key is missing the required scope.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"status":{"type":"number","example":403,"isRequired":true,"uniqueKey":"error.status","typeLabel":"number"},"requestId":{"type":"string","example":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f","description":"Correlation id - quote it in support requests.","isRequired":true,"uniqueKey":"error.requestId","typeLabel":"string"},"details":{"description":"Field-level validation messages (present on validation errors).","example":["name should not be empty"],"type":"array","items":{"type":"string","uniqueKey":"error.details.items.[INDEX]","typeLabel":"string"},"uniqueKey":"error.details","typeLabel":"string[]"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying (present on 429 responses).","example":30,"uniqueKey":"error.retryAfter","typeLabel":"number"}},"required":["type","code","message","status","requestId"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"example":{"error":{"type":"invalid_request_error","code":"not_found","message":"Resource not found.","status":404,"requestId":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"}},"examples":{"Example":{"title":"Example","value":{"error":{"type":"invalid_request_error","code":"not_found","message":"Resource not found.","status":404,"requestId":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"}}}},"exampleType":"examples"}},"exampleType":"examples"},"e7f32cee-738d-46dd-ad2b-a20e74839fd1":{"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.\n\nThe 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":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"authorization_error","description":"Broad error class.","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"code":{"type":"string","example":"permission_denied","description":"Stable machine-readable code to switch on.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","example":"This API key is missing the required scope.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"status":{"type":"number","example":403,"isRequired":true,"uniqueKey":"error.status","typeLabel":"number"},"requestId":{"type":"string","example":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f","description":"Correlation id - quote it in support requests.","isRequired":true,"uniqueKey":"error.requestId","typeLabel":"string"},"details":{"description":"Field-level validation messages (present on validation errors).","example":["name should not be empty"],"type":"array","items":{"type":"string","uniqueKey":"error.details.items.[INDEX]","typeLabel":"string"},"uniqueKey":"error.details","typeLabel":"string[]"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying (present on 429 responses).","example":30,"uniqueKey":"error.retryAfter","typeLabel":"number"}},"required":["type","code","message","status","requestId"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"example":{"error":{"type":"invalid_request_error","code":"conflict","message":"The request conflicts with an existing resource.","status":409,"requestId":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"}},"examples":{"Example":{"title":"Example","value":{"error":{"type":"invalid_request_error","code":"conflict","message":"The request conflicts with an existing resource.","status":409,"requestId":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"}}}},"exampleType":"examples"}},"exampleType":"examples"},"0398ebb3-a992-4154-9a25-649730ebb0c5":{"description":"The Idempotency-Key was already used with a different request body. Use a new key for a new operation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"authorization_error","description":"Broad error class.","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"code":{"type":"string","example":"permission_denied","description":"Stable machine-readable code to switch on.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","example":"This API key is missing the required scope.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"status":{"type":"number","example":403,"isRequired":true,"uniqueKey":"error.status","typeLabel":"number"},"requestId":{"type":"string","example":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f","description":"Correlation id - quote it in support requests.","isRequired":true,"uniqueKey":"error.requestId","typeLabel":"string"},"details":{"description":"Field-level validation messages (present on validation errors).","example":["name should not be empty"],"type":"array","items":{"type":"string","uniqueKey":"error.details.items.[INDEX]","typeLabel":"string"},"uniqueKey":"error.details","typeLabel":"string[]"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying (present on 429 responses).","example":30,"uniqueKey":"error.retryAfter","typeLabel":"number"}},"required":["type","code","message","status","requestId"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"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"}},"examples":{"Example":{"title":"Example","value":{"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"}}}},"exampleType":"examples"}},"exampleType":"examples"},"c06ecfc2-8827-4df2-bcc9-25983dc8a3ae":{"description":"Rate limit exceeded - retry after the interval in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"authorization_error","description":"Broad error class.","isRequired":true,"uniqueKey":"error.type","typeLabel":"string"},"code":{"type":"string","example":"permission_denied","description":"Stable machine-readable code to switch on.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","example":"This API key is missing the required scope.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"status":{"type":"number","example":403,"isRequired":true,"uniqueKey":"error.status","typeLabel":"number"},"requestId":{"type":"string","example":"e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f","description":"Correlation id - quote it in support requests.","isRequired":true,"uniqueKey":"error.requestId","typeLabel":"string"},"details":{"description":"Field-level validation messages (present on validation errors).","example":["name should not be empty"],"type":"array","items":{"type":"string","uniqueKey":"error.details.items.[INDEX]","typeLabel":"string"},"uniqueKey":"error.details","typeLabel":"string[]"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying (present on 429 responses).","example":30,"uniqueKey":"error.retryAfter","typeLabel":"number"}},"required":["type","code","message","status","requestId"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"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}},"examples":{"Example":{"title":"Example","value":{"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}}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"e530ccb3-9543-4396-bc5d-fb05e7b0155d":{"ApiKey":{"scheme":"bearer","bearerFormat":"mb_live_…","type":"http","scopes":[],"schemeName":"ApiKey"}}},"servers":{"e914a309-44fa-4a4c-b571-a32c0fb4ed0a":{"url":"https://api.mailbeast.ai"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"scheme":"bearer","bearerFormat":"mb_live_…","type":"http","scopes":[],"schemeName":"ApiKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Bearer authentication header of the form `Bearer \u003ctoken>`, where `\u003ctoken>` is your auth token.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"ApiKey","name":"Authorization"}],"title":"ApiKey"}]},"originalFileLocation":"openapi.json"},"subdomain":"mail-beast-ai","siteName":"MailBeast API","title":"Move leads into a subsequence - MailBeast API","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-04T20:25:28.916Z","originalFileLocation":"api-reference/subsequences/move-leads-into-a-subsequence.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"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.\">\u003cmeta data-mint-head name=\"application-name\" content=\"MailBeast API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/mail-beast-ai/WJNHEBup3U7XmwP7/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/mail-beast-ai/WJNHEBup3U7XmwP7/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/mail-beast-ai/WJNHEBup3U7XmwP7/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/mail-beast-ai/WJNHEBup3U7XmwP7/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/mail-beast-ai/WJNHEBup3U7XmwP7/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/mail-beast-ai/WJNHEBup3U7XmwP7/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/mail-beast-ai/WJNHEBup3U7XmwP7/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/mail-beast-ai/WJNHEBup3U7XmwP7/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/mail-beast-ai/WJNHEBup3U7XmwP7/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Move leads into a subsequence - MailBeast API\">\u003cmeta data-mint-head property=\"og:description\" content=\"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.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"MailBeast API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://developer.mailbeast.ai/api-reference/subsequences/move-leads-into-a-subsequence\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://mail-beast-ai.mintlify.app/_mintlify/api/og/v2?division=Subsequences\u0026amp;title=Move+leads+into+a+subsequence\u0026amp;description=Move+leads+of+the+main+campaign+into+the+subsequence%2C+by+%60leadIds%60+or+%60emails%60+%28up+to+1000%29.+Their+remaining+main-sequence+emails+are+canceled+and+the+subsequen\u0026amp;theme=deee3b5723542dabe22142b2\u0026amp;signature=49a61f713d8f48eef6f02737bf3b3c4f57670db953e9f14ec6a5aaf7162b464a\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Move leads into a subsequence - MailBeast API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"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.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://mail-beast-ai.mintlify.app/_mintlify/api/og/v2?division=Subsequences\u0026amp;title=Move+leads+into+a+subsequence\u0026amp;description=Move+leads+of+the+main+campaign+into+the+subsequence%2C+by+%60leadIds%60+or+%60emails%60+%28up+to+1000%29.+Their+remaining+main-sequence+emails+are+canceled+and+the+subsequen\u0026amp;theme=deee3b5723542dabe22142b2\u0026amp;signature=49a61f713d8f48eef6f02737bf3b3c4f57670db953e9f14ec6a5aaf7162b464a\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/mail-beast-ai/WJNHEBup3U7XmwP7/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"MailBeast API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2F62E8\">\u003clink data-mint-head rel=\"canonical\" href=\"https://developer.mailbeast.ai/api-reference/subsequences/move-leads-into-a-subsequence\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/subsequences/move-leads-into-a-subsequence.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://developer.mailbeast.ai/#organization\",\"name\":\"MailBeast API\",\"url\":\"https://developer.mailbeast.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/mail-beast-ai/wTQEP6MPos1XZJQD/logo/light.svg?fit=max\u0026auto=format\u0026n=wTQEP6MPos1XZJQD\u0026q=85\u0026s=aeac906ba6340f321596e4d877c72bf1\"}},{\"@type\":\"WebSite\",\"@id\":\"https://developer.mailbeast.ai#website\",\"name\":\"MailBeast API\",\"url\":\"https://developer.mailbeast.ai\",\"publisher\":{\"@id\":\"https://developer.mailbeast.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://developer.mailbeast.ai/api-reference/subsequences/move-leads-into-a-subsequence#webpage\",\"url\":\"https://developer.mailbeast.ai/api-reference/subsequences/move-leads-into-a-subsequence\",\"name\":\"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.\",\"dateModified\":\"2026-11-04T20:25:28.916Z\",\"isPartOf\":{\"@id\":\"https://developer.mailbeast.ai#website\"},\"breadcrumb\":{\"@id\":\"https://developer.mailbeast.ai/api-reference/subsequences/move-leads-into-a-subsequence#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://developer.mailbeast.ai/api-reference/subsequences/move-leads-into-a-subsequence#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Subsequences\",\"item\":\"https://developer.mailbeast.ai/api-reference/subsequences/create-a-subsequence\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Move leads into a subsequence\",\"item\":\"https://developer.mailbeast.ai/api-reference/subsequences/move-leads-into-a-subsequence\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://developer.mailbeast.ai/api-reference/subsequences/move-leads-into-a-subsequence#apireference\",\"headline\":\"Move leads into a subsequence\",\"name\":\"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.\",\"url\":\"https://developer.mailbeast.ai/api-reference/subsequences/move-leads-into-a-subsequence\",\"mainEntityOfPage\":{\"@id\":\"https://developer.mailbeast.ai/api-reference/subsequences/move-leads-into-a-subsequence#webpage\"},\"dateModified\":\"2026-11-04T20:25:28.916Z\",\"publisher\":{\"@id\":\"https://developer.mailbeast.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://developer.mailbeast.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"MailBeast API\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"MailBeast API","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":"/introduction"}]},{"tab":"API Reference","groups":[{"group":"Lead Finder","pages":[{"title":"List lead searches","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/lead-searches","href":"/api-reference/lead-finder/list-lead-searches"},{"title":"Get a lead search","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/lead-searches/{id}","href":"/api-reference/lead-finder/get-a-lead-search"}]},{"group":"Email Accounts","pages":[{"title":"Connect mailboxes","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/accounts","href":"/api-reference/email-accounts/connect-mailboxes"},{"title":"List mailboxes","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/accounts","href":"/api-reference/email-accounts/list-mailboxes"},{"title":"Get a mailbox","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/accounts/{id}","href":"/api-reference/email-accounts/get-a-mailbox"},{"title":"Update a mailbox","deprecated":null,"version":null,"openapi":"/openapi.json patch /v1/accounts/{id}","href":"/api-reference/email-accounts/update-a-mailbox"},{"title":"Delete a mailbox","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/accounts/{id}","href":"/api-reference/email-accounts/delete-a-mailbox"},{"title":"Bulk update mailboxes","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/accounts/bulk","href":"/api-reference/email-accounts/bulk-update-mailboxes"},{"title":"Verification result","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/accounts/{id}/verification","href":"/api-reference/email-accounts/verification-result"},{"title":"Pause a mailbox","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/accounts/{id}/pause","href":"/api-reference/email-accounts/pause-a-mailbox"},{"title":"Resume a mailbox","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/accounts/{id}/resume","href":"/api-reference/email-accounts/resume-a-mailbox"},{"title":"Start OAuth connect","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/accounts/oauth/{provider}/init","href":"/api-reference/email-accounts/start-oauth-connect"},{"title":"Poll OAuth connect","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/accounts/oauth/{provider}/status","href":"/api-reference/email-accounts/poll-oauth-connect"}]},{"group":"Campaigns","pages":[{"title":"Create a campaign","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/campaigns","href":"/api-reference/campaigns/create-a-campaign"},{"title":"Start campaign","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/campaigns/{id}/start","href":"/api-reference/campaigns/start-campaign"},{"title":"Pause campaign","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/campaigns/{id}/pause","href":"/api-reference/campaigns/pause-campaign"},{"title":"Resume campaign","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/campaigns/{id}/resume","href":"/api-reference/campaigns/resume-campaign"},{"title":"Send a test email","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/campaigns/{id}/test-email","href":"/api-reference/campaigns/send-a-test-email"},{"title":"List campaigns","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/campaigns","href":"/api-reference/campaigns/list-campaigns"},{"title":"Get a campaign","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/campaigns/{id}","href":"/api-reference/campaigns/get-a-campaign"},{"title":"Update a campaign","deprecated":null,"version":null,"openapi":"/openapi.json patch /v1/campaigns/{id}","href":"/api-reference/campaigns/update-a-campaign"},{"title":"Delete a campaign","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/campaigns/{id}","href":"/api-reference/campaigns/delete-a-campaign"},{"title":"Campaign send status","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/campaigns/{id}/status","href":"/api-reference/campaigns/campaign-send-status"}]},{"group":"Subsequences","pages":[{"title":"Create a subsequence","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/campaigns/{id}/subsequences","href":"/api-reference/subsequences/create-a-subsequence"},{"title":"List subsequences of a campaign","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/campaigns/{id}/subsequences","href":"/api-reference/subsequences/list-subsequences-of-a-campaign"},{"title":"Get a subsequence","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/subsequences/{id}","href":"/api-reference/subsequences/get-a-subsequence"},{"title":"Update a subsequence","deprecated":null,"version":null,"openapi":"/openapi.json patch /v1/subsequences/{id}","href":"/api-reference/subsequences/update-a-subsequence"},{"title":"Delete a subsequence","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/subsequences/{id}","href":"/api-reference/subsequences/delete-a-subsequence"},{"title":"Turn a subsequence on","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/subsequences/{id}/enable","href":"/api-reference/subsequences/turn-a-subsequence-on"},{"title":"Pause a subsequence","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/subsequences/{id}/pause","href":"/api-reference/subsequences/pause-a-subsequence"},{"title":"Resume a subsequence","description":"Turn a paused subsequence back on - the same as `/enable`: leads that waited continue (real email), new matching leads enter again. `enrollExisting: true` also enrolls the leads that matched while it was off. 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.\n\nRequires one of the following scopes: `campaigns:lifecycle`, `campaigns:all`, `all:all`.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/subsequences/{id}/resume","href":"/api-reference/subsequences/resume-a-subsequence"},{"title":"Move leads into a subsequence","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/subsequences/{id}/leads","href":"/api-reference/subsequences/move-leads-into-a-subsequence"}]},{"group":"Emails","pages":[{"title":"List emails","description":"List emails across your mailboxes, newest first. Results carry a `snippet` preview but never the message body; fetch a single email to read it. Filter by mailbox, campaign, conversation, lead, read state, direction, folder, date, or full-text search.\n\nRequires one of the following scopes: `emails:read`, `emails:all`, `all:read`, `all:all`.","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/emails","href":"/api-reference/emails/list-emails"},{"title":"Get an email","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/emails/{id}","href":"/api-reference/emails/get-an-email"},{"title":"Reply to an email","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/emails/{id}/reply","href":"/api-reference/emails/reply-to-an-email"},{"title":"Forward an email","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/emails/{id}/forward","href":"/api-reference/emails/forward-an-email"},{"title":"Count unread emails","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/emails/unread/count","href":"/api-reference/emails/count-unread-emails"},{"title":"Mark a conversation read","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/threads/{id}/read","href":"/api-reference/emails/mark-a-conversation-read"}]},{"group":"Leads","pages":[{"title":"Add leads","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/campaigns/{cid}/leads","href":"/api-reference/leads/add-leads"},{"title":"List campaign leads","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/campaigns/{cid}/leads","href":"/api-reference/leads/list-campaign-leads"},{"title":"Get a lead","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/campaigns/{cid}/leads/{leadId}","href":"/api-reference/leads/get-a-lead"},{"title":"Update a lead","deprecated":null,"version":null,"openapi":"/openapi.json patch /v1/campaigns/{cid}/leads/{leadId}","href":"/api-reference/leads/update-a-lead"},{"title":"Delete a lead","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/campaigns/{cid}/leads/{leadId}","href":"/api-reference/leads/delete-a-lead"},{"title":"Bulk mutate leads","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/campaigns/{cid}/leads/mutate","href":"/api-reference/leads/bulk-mutate-leads"},{"title":"Search leads by email","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/leads/search","href":"/api-reference/leads/search-leads-by-email"}]},{"group":"API Keys","pages":[{"title":"Create an API key","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/api-keys","href":"/api-reference/api-keys/create-an-api-key"},{"title":"List API keys","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/api-keys","href":"/api-reference/api-keys/list-api-keys"},{"title":"Delete an API key","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/api-keys/{id}","href":"/api-reference/api-keys/delete-an-api-key"}]},{"group":"Workspace","pages":[{"title":"Current usage","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/usage","href":"/api-reference/workspace/current-usage"},{"title":"Current usage for one limit","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/usage/{limitType}","href":"/api-reference/workspace/current-usage-for-one-limit"},{"title":"Subscription","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/account/subscription","href":"/api-reference/workspace/subscription"},{"title":"Workspace identity","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/workspace","href":"/api-reference/workspace/workspace-identity"}]},{"group":"Analytics","pages":[{"title":"Campaign analytics","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/campaigns/{id}/analytics","href":"/api-reference/analytics/campaign-analytics"},{"title":"Campaign analytics over time","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/campaigns/{id}/analytics/timeseries","href":"/api-reference/analytics/campaign-analytics-over-time"},{"title":"Workspace analytics roll-up","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/campaigns/analytics/overview","href":"/api-reference/analytics/workspace-analytics-roll-up"}]}]}]},"basePath":"","title":"Move leads into a subsequence - MailBeast API","buildId":"dpl_9VVk5y1P8k1ATeJguVngy9Q3cmbD","deploymentId":"dpl_9VVk5y1P8k1ATeJguVngy9Q3cmbD","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-DX1Meug0.js","utils-B_OMIQVC.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-ChxhRPMa.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-CuKvD8Iv.js","snippetPresets-C5d7p2hp.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-CfHcE8m4.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-C1zZV314.js","shallow-CmQhqCJn.js","getApiPlaygroundDisplay-YRo9s1O7.js","CodeSnippet-RN1MTdfk.js","CodeSnippets-DKLPHxJA.js","Page-BAvA99GL.js","getPastedJson-bz0M41mU.js","icon-CsmhpPrv.js","MethodPill-CNGsVE77.js","DuplicateIcon-DilfU_Z2.js","createIcon-BdsYzQck.js","DynamicMarkdown-CbqEDjbV.js","SectionHeading-O6hXpFCN.js","axios-vUo_bRtp.js","Markdown-nKm-uidQ.js","clsx-ClVdStUn.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-CIQkMg3R.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-ImrFS4Fy.js"]}