Update a subsequence
curl --request PATCH \
--url https://api.mailbeast.ai/v1/subsequences/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Interested - book a call (v2)",
"settings": {},
"sequence": [
{
"subject": "",
"body": "<p>Hi {{first_name}}, here is my calendar: …</p>",
"variants": [
{
"subject": "",
"body": "<p>Hi {{first_name}}, here is my calendar: …</p>",
"isActive": true
}
],
"delayDays": 2,
"delayHours": 0
}
],
"position": 1
}
'import requests
url = "https://api.mailbeast.ai/v1/subsequences/{id}"
payload = {
"name": "Interested - book a call (v2)",
"settings": {},
"sequence": [
{
"subject": "",
"body": "<p>Hi {{first_name}}, here is my calendar: …</p>",
"variants": [
{
"subject": "",
"body": "<p>Hi {{first_name}}, here is my calendar: …</p>",
"isActive": True
}
],
"delayDays": 2,
"delayHours": 0
}
],
"position": 1
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Interested - book a call (v2)',
settings: {},
sequence: [
{
subject: '',
body: JSON.stringify('<p>Hi {{first_name}}, here is my calendar: …</p>'),
variants: [
{
subject: '',
body: JSON.stringify('<p>Hi {{first_name}}, here is my calendar: …</p>'),
isActive: true
}
],
delayDays: 2,
delayHours: 0
}
],
position: 1
})
};
fetch('https://api.mailbeast.ai/v1/subsequences/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mailbeast.ai/v1/subsequences/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Interested - book a call (v2)',
'settings' => [
],
'sequence' => [
[
'subject' => '',
'body' => '<p>Hi {{first_name}}, here is my calendar: …</p>',
'variants' => [
[
'subject' => '',
'body' => '<p>Hi {{first_name}}, here is my calendar: …</p>',
'isActive' => true
]
],
'delayDays' => 2,
'delayHours' => 0
]
],
'position' => 1
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mailbeast.ai/v1/subsequences/{id}"
payload := strings.NewReader("{\n \"name\": \"Interested - book a call (v2)\",\n \"settings\": {},\n \"sequence\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"variants\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"isActive\": true\n }\n ],\n \"delayDays\": 2,\n \"delayHours\": 0\n }\n ],\n \"position\": 1\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.mailbeast.ai/v1/subsequences/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Interested - book a call (v2)\",\n \"settings\": {},\n \"sequence\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"variants\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"isActive\": true\n }\n ],\n \"delayDays\": 2,\n \"delayHours\": 0\n }\n ],\n \"position\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mailbeast.ai/v1/subsequences/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Interested - book a call (v2)\",\n \"settings\": {},\n \"sequence\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"variants\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"isActive\": true\n }\n ],\n \"delayDays\": 2,\n \"delayHours\": 0\n }\n ],\n \"position\": 1\n}"
response = http.request(request)
puts response.read_body{
"id": "5b2f3c4d-6e7f-4a81-9b0c-1d2e3f4a5b6c",
"campaignId": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60",
"name": "Interested - book a call",
"position": 1,
"status": "active",
"enabled": true,
"state": "active",
"settings": {
"trigger": {
"any": [
{
"kind": "lead_status",
"statuses": [
"lead_replied_interested",
"lead_replied_meeting_request"
],
"phrases": [
"pricing",
"more info"
],
"when": {
"mode": "after_main_sequence",
"waitDays": 0
},
"urlContains": "/pricing",
"waitDays": 3
}
],
"sources": [
"main"
],
"filters": [
{
"kind": "tag",
"op": "has_any",
"values": [
"vip"
],
"field": "industry",
"value": "<string>",
"emails": 50,
"atLeast": 25
}
]
},
"start": {
"mode": "delay",
"amount": 1,
"unit": "hours",
"offsetDays": 1,
"withoutDate": {
"mode": "delay",
"days": 7
},
"maxDaysAhead": 120
},
"sending": {
"schedule": "inherit",
"dailyLimit": {
"mode": "inherit",
"value": 30
}
}
},
"sequence": [
{
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"subject": "Quick question about {{company_name}}",
"body": "<p>Hi {{first_name}}, …</p>",
"delayDays": 0,
"delayHours": 0,
"variants": [
{
"id": "b3f1a2c4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
"label": "A",
"subject": "Quick question about {{company_name}}",
"body": "<p>Hi {{first_name}}, …</p>",
"isActive": true
}
]
}
],
"counters": {
"entered": 42,
"waiting": 3,
"inProgress": 12,
"replied": 9,
"positive": 5,
"ended": 30
},
"nextStartAt": "2023-11-07T05:31:56Z",
"createdAt": "2026-10-28T08:00:00.000Z"
}{
"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": "not_found",
"message": "Resource not found.",
"status": 404,
"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
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.
PATCH
/
v1
/
subsequences
/
{id}
Update a subsequence
curl --request PATCH \
--url https://api.mailbeast.ai/v1/subsequences/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Interested - book a call (v2)",
"settings": {},
"sequence": [
{
"subject": "",
"body": "<p>Hi {{first_name}}, here is my calendar: …</p>",
"variants": [
{
"subject": "",
"body": "<p>Hi {{first_name}}, here is my calendar: …</p>",
"isActive": true
}
],
"delayDays": 2,
"delayHours": 0
}
],
"position": 1
}
'import requests
url = "https://api.mailbeast.ai/v1/subsequences/{id}"
payload = {
"name": "Interested - book a call (v2)",
"settings": {},
"sequence": [
{
"subject": "",
"body": "<p>Hi {{first_name}}, here is my calendar: …</p>",
"variants": [
{
"subject": "",
"body": "<p>Hi {{first_name}}, here is my calendar: …</p>",
"isActive": True
}
],
"delayDays": 2,
"delayHours": 0
}
],
"position": 1
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Interested - book a call (v2)',
settings: {},
sequence: [
{
subject: '',
body: JSON.stringify('<p>Hi {{first_name}}, here is my calendar: …</p>'),
variants: [
{
subject: '',
body: JSON.stringify('<p>Hi {{first_name}}, here is my calendar: …</p>'),
isActive: true
}
],
delayDays: 2,
delayHours: 0
}
],
position: 1
})
};
fetch('https://api.mailbeast.ai/v1/subsequences/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mailbeast.ai/v1/subsequences/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Interested - book a call (v2)',
'settings' => [
],
'sequence' => [
[
'subject' => '',
'body' => '<p>Hi {{first_name}}, here is my calendar: …</p>',
'variants' => [
[
'subject' => '',
'body' => '<p>Hi {{first_name}}, here is my calendar: …</p>',
'isActive' => true
]
],
'delayDays' => 2,
'delayHours' => 0
]
],
'position' => 1
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mailbeast.ai/v1/subsequences/{id}"
payload := strings.NewReader("{\n \"name\": \"Interested - book a call (v2)\",\n \"settings\": {},\n \"sequence\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"variants\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"isActive\": true\n }\n ],\n \"delayDays\": 2,\n \"delayHours\": 0\n }\n ],\n \"position\": 1\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.mailbeast.ai/v1/subsequences/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Interested - book a call (v2)\",\n \"settings\": {},\n \"sequence\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"variants\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"isActive\": true\n }\n ],\n \"delayDays\": 2,\n \"delayHours\": 0\n }\n ],\n \"position\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mailbeast.ai/v1/subsequences/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Interested - book a call (v2)\",\n \"settings\": {},\n \"sequence\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"variants\": [\n {\n \"subject\": \"\",\n \"body\": \"<p>Hi {{first_name}}, here is my calendar: …</p>\",\n \"isActive\": true\n }\n ],\n \"delayDays\": 2,\n \"delayHours\": 0\n }\n ],\n \"position\": 1\n}"
response = http.request(request)
puts response.read_body{
"id": "5b2f3c4d-6e7f-4a81-9b0c-1d2e3f4a5b6c",
"campaignId": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60",
"name": "Interested - book a call",
"position": 1,
"status": "active",
"enabled": true,
"state": "active",
"settings": {
"trigger": {
"any": [
{
"kind": "lead_status",
"statuses": [
"lead_replied_interested",
"lead_replied_meeting_request"
],
"phrases": [
"pricing",
"more info"
],
"when": {
"mode": "after_main_sequence",
"waitDays": 0
},
"urlContains": "/pricing",
"waitDays": 3
}
],
"sources": [
"main"
],
"filters": [
{
"kind": "tag",
"op": "has_any",
"values": [
"vip"
],
"field": "industry",
"value": "<string>",
"emails": 50,
"atLeast": 25
}
]
},
"start": {
"mode": "delay",
"amount": 1,
"unit": "hours",
"offsetDays": 1,
"withoutDate": {
"mode": "delay",
"days": 7
},
"maxDaysAhead": 120
},
"sending": {
"schedule": "inherit",
"dailyLimit": {
"mode": "inherit",
"value": 30
}
}
},
"sequence": [
{
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"subject": "Quick question about {{company_name}}",
"body": "<p>Hi {{first_name}}, …</p>",
"delayDays": 0,
"delayHours": 0,
"variants": [
{
"id": "b3f1a2c4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
"label": "A",
"subject": "Quick question about {{company_name}}",
"body": "<p>Hi {{first_name}}, …</p>",
"isActive": true
}
]
}
],
"counters": {
"entered": 42,
"waiting": 3,
"inProgress": 12,
"replied": 9,
"positive": 5,
"ended": 30
},
"nextStartAt": "2023-11-07T05:31:56Z",
"createdAt": "2026-10-28T08:00:00.000Z"
}{
"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": "not_found",
"message": "Resource not found.",
"status": 404,
"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
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
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.
Maximum string length:
255Example:
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Path Parameters
Subsequence id.
Example:
"5b2f3c4d-6e7f-4a81-9b0c-1d2e3f4a5b6c"
Body
application/json
Maximum string length:
255Example:
"Interested - book a call (v2)"
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.
Show child attributes
Show child attributes
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).
Required array length:
1 - 20 elementsShow child attributes
Show child attributes
Position among the subsequences of the campaign (1 = first). When one event matches several subsequences, the lead enters the first one.
Required range:
1 <= x <= 10000Example:
1
Response
Example:
"5b2f3c4d-6e7f-4a81-9b0c-1d2e3f4a5b6c"
The campaign this subsequence belongs to.
Example:
"a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60"
Example:
"Interested - book a call"
Order among the campaign's subsequences (1 = first): when one event matches several, the lead enters the first.
Example:
1
Lifecycle status, same vocabulary as campaigns: draft / paused = off, active = on.
Available options:
draft, scheduled, active, paused, stopped, completed, failed Example:
"active"
Whether it is turned on (/enable / /pause). A subsequence of a draft campaign stays draft while on - it starts with the campaign.
Example:
true
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.
Available options:
draft, starts_with_campaign, active, paused, paused_with_campaign, stopped_campaign_ended, paused_requires_plan, cant_start, waiting_restart Example:
"active"
Show child attributes
Show child attributes
The emails of the subsequence - the same shape as a campaign's sequence. A step with an empty subject replies in the same thread.
Show child attributes
Show child attributes
All-time counters (not limited to a period).
Show child attributes
Show child attributes
When the next waiting lead gets its first email; null when nobody is waiting.
Example:
"2026-10-28T08:00:00.000Z"