Campaigns
Update campaign
Updates mutable campaign fields. Mailboxes can be replaced wholesale with mailbox_ids, or incrementally edited with add_mailbox_ids and remove_mailbox_ids. Tags can be replaced with tag_ids, or incrementally edited with add_tag_ids and remove_tag_ids.
recipient_esps sets which email providers the campaign sends first emails to. auto_esp_match makes each mailbox prefer leads on its own provider. Both apply only to a lead's first email. Follow-ups and replies always use the mailbox that sent the first email.
follow_up_share sets how often a mailbox sends a due follow-up instead of a new lead: 100 means follow-ups first, 0 new leads first. max_new_per_day sets how many new leads the campaign may start each day in its time zone: null means no limit, 0 none.
The response carries warnings next to data. The update is saved even when there are warnings. Read them after changing recipient_esps, auto_esp_match or the mailbox list: they say when leads are left without a first email, and when removing a mailbox leaves follow-ups waiting.
/v1/campaigns/{id}Authorization
bearerAuth Use an account API key in the Authorization header: Authorization: Bearer f_....
In: header
Path Parameters
Campaign id.
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Send window. null means send 24/7.
IANA timezone, e.g. America/Chicago.
Inclusive start hour in the campaign timezone.
0 <= value <= 23Exclusive end hour in the campaign timezone.
0 <= value <= 23Allowed weekdays. Null/empty = every day.
Optional start minute. Defaults to 0 when omitted.
0 <= value <= 59Optional end minute. Defaults to 0 when omitted.
0 <= value <= 59Replace the campaign calendar bounds. Omitted leaves the current dates unchanged. null clears start_on and pause_on. start_at/pause_at are ignored on write.
IANA timezone used to interpret start_on and pause_on.
First local sending date. Null means start as soon as the campaign is launched.
dateExclusive local pause date. Null means the campaign never auto-pauses.
dateRead-only UTC instant of local midnight on start_on. Ignored on write.
date-timeRead-only UTC instant of local midnight on pause_on. Ignored on write.
date-timeReplace all tag assignments on the campaign.
ESP filter: the email providers this campaign sends first emails to. Omit to leave it unchanged. Send one or more of google, microsoft and other, each at most once. other is every provider that is not Google or Microsoft. All three and null both mean every provider. An empty list is rejected. The filter applies only to a lead's first email. Follow-ups and replies always use the mailbox that sent the first email. When a filter applies, a lead whose email provider has not been checked yet waits for the check, usually about a minute.
1 <= itemsOmit to leave it unchanged. When true, each mailbox prefers first emails to leads on its own email provider (the mailbox's sending_esp). It is best effort and never delays sending: a mailbox with no matching lead takes any lead the filters allow. The recipient_esps filters on the campaign and on its mailboxes always win over matching. Matching applies only to a lead's first email. Follow-ups and replies always use the mailbox that sent the first email.
Omit to leave it unchanged. How often a mailbox sends a due follow-up instead of a new lead, in percent: 100 means follow-ups first, 0 new leads first. From 0 to 100 in steps of 10. The default is 50.
100 <= value <= 100Omit to leave it unchanged. Send null to remove the limit. New leads per day: how many people who have not been emailed yet the campaign may start each day, counted by calendar day in the campaign's time zone. null means no limit and 0 means no new leads. Follow-ups are not limited, and unused room does not carry over. New leads go out in the order they were added. A lower number applies from the next open send slot, so slots already booked still send; pause the campaign to stop at once.
0 <= value <= 10000curl -X PATCH "https://example.com/v1/campaigns/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "name": "Q2 Pipeline Refresh", "sending_interval_seconds": 1800, "add_mailbox_ids": [ "c23da7b6-df4e-4d2f-b100-4bb07b7d38d7" ], "recipient_esps": [ "microsoft", "other" ], "follow_up_share": 70, "max_new_per_day": 14 }'{ "data": { "id": "1d8dc901-3d2d-4d9f-9dcc-4f8b3aa1a1fb", "name": "Q2 Pipeline Refresh", "status": "running", "display_status": "running", "sending_interval_seconds": 1800, "recipient_esps": [ "microsoft", "other" ], "auto_esp_match": false, "follow_up_share": 70, "max_new_per_day": 14, "created_at": "2026-05-21T18:00:00.000Z" }, "warnings": [ { "code": "esp_leads_unreachable", "severity": "warning", "message": "4,049 Gmail leads won't be emailed. This campaign isn't set to send to Gmail. That leaves 715 leads to email, about 7 days of sending." } ]}{ "error": { "type": "invalid_request_error", "code": "invalid_flow", "message": "Flow validation failed" }, "details": [ { "path": "nodes[1].data.variants[0].id", "code": "invalid_variant_id", "message": "Email variants must have a stable UUID id." } ]}{ "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "A valid Furnace API key is required" }}{ "error": { "type": "permission_error", "code": "smartlead_read_only", "message": "Smartlead campaigns are read-only via the API" }}{ "error": { "type": "invalid_request_error", "code": "campaign_not_found", "message": "Campaign not found" }}{ "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit exceeded for this account" }}{ "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error" }}