Campaigns

Update a campaign

Partial update - only the supplied sections are touched. accounts, tags and sequence, when present, REPLACE the existing set.

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

patch/v1/campaigns/{id}

Request

  • Base URL: https://api.mailbeast.ai
  • URL: https://api.mailbeast.ai/v1/campaigns/{id}
  • Auth: HTTP bearer

Path parameters

idstring uuid required
Example:a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60

Headers

Idempotency-Keystring
Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890

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.

Request body

namestring
accountsstring[]

When supplied, REPLACES the attached SMTP account set — the mailboxes the campaign sends from when settings.useAllAccounts is false. While useAllAccounts is true the campaign sends from every connected mailbox and this list does not limit it.

tagsstring[]

When supplied, REPLACES the campaign's tags ([] removes them all). Campaign tag ids to put on the campaign. Read the ids from tags[] on any campaign; tags themselves are created in the dashboard. Mailbox tag ids are a different dictionary and are rejected.

Example request

{
  "name": "Q4 Launch (revised)",
  "schedule": {
    "mode": "advanced",
    "intervals": [
      {
        "day": 1,
        "startMinutes": 570,
        "endMinutes": 1050,
        "enabled": true
      }
    ],
    "timezone": "America/New_York",
    "sendingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "sendingMinutesStart": 540,
    "sendingMinutesEnd": 1020,
    "dailyLimit": 50
  },
  "settings": {
    "trackOpens": true,
    "trackClicks": true,
    "stopOnReply": true,
    "stopOnBounce": true,
    "stopCompanyOnReply": true,
    "skipInvalidEmails": true,
    "skipUnknownEmails": true,
    "emailProviderMatching": true,
    "unsubscribeLinkHeader": true,
    "newLeadsRatio": 80,
    "keepActiveWhenNoLeads": true,
    "hubspotSyncEnabled": true
  },
  "sequence": [
    {
      "subject": "Quick question about {{company_name}}",
      "body": "<p>Hi {{first_name}}, …</p>",
      "variants": [
        {
          "subject": "Quick question about {{company_name}}",
          "body": "<p>Hi {{first_name}}, …</p>",
          "isActive": true
        }
      ]
    }
  ],
  "accounts": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "tags": [
    "5c9b1e77-2f4a-4c31-9d8e-1a2b3c4d5e6f"
  ]
}

Response

idstring uuid required
namestring required
status'draft' | 'scheduled' | 'active' | 'paused' | 'stopped' | 'completed' | 'failed' required
accountsstring[]

Attached SMTP account ids - included on the detail view. The campaign sends only from these when settings.useAllAccounts is false; while it is true, from every connected mailbox of the workspace.

createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Q4 Product Launch Outreach",
  "status": "draft",
  "schedule": {
    "mode": "simple",
    "intervals": [
      {
        "day": 1,
        "startMinutes": 570,
        "endMinutes": 1050,
        "enabled": true
      }
    ],
    "timezone": "America/New_York",
    "sendingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "sendingMinutesStart": 540,
    "sendingMinutesEnd": 1020,
    "dailyLimit": 50
  },
  "settings": {
    "trackOpens": true,
    "trackClicks": true,
    "stopOnReply": true,
    "stopOnBounce": true,
    "stopCompanyOnReply": true,
    "skipInvalidEmails": true,
    "skipUnknownEmails": true,
    "emailProviderMatching": true,
    "unsubscribeLinkHeader": true,
    "newLeadsRatio": 80,
    "hubspotSyncEnabled": true
  },
  "metrics": {
    "leadsCount": 150,
    "sent": 120,
    "opens": 90,
    "clicks": 25,
    "replies": 12
  },
  "sequence": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "subject": "Quick question about {{company_name}}",
      "body": "<p>Hi {{first_name}}, …</p>",
      "variants": [
        {
          "id": "b3f1a2c4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
          "label": "A",
          "subject": "Quick question about {{company_name}}",
          "body": "<p>Hi {{first_name}}, …</p>",
          "isActive": true
        }
      ]
    }
  ],
  "accounts": [
    "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93"
  ],
  "tags": [
    {
      "id": "5c9b1e77-2f4a-4c31-9d8e-1a2b3c4d5e6f",
      "name": "client-acme",
      "color": "#4F46E5"
    }
  ],
  "createdAt": "2026-07-11T08:00:00.000Z",
  "updatedAt": "2026-07-11T10:30:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.